The angry programmer?

My wife thinks I should start another blog named "Ulriks programming nightmares". Or maybe just add another topic of this blog where I mention examples of programmed systems that aren't good. Or to be more precise, where the programmer was too lazy to do a good job, which really gets me going. Unfortunately I get upset when I see it among the students which is a bit harsh, they are here to learn after all.
The examples I have seen so far is everything from the logic of the elevators at the university to how the booking system of SJ places people at a train. Seriously, if there are 3 reserved seats in a wagon, why must two of them be next to each other?
Enough ranting, but is this a good idea to expand the topic of the blog with? Coming to think of it, there must already be sites like that out there. If not there should be, it is always more educational to learn from bad examples than good.

Documentation

When it comes to documentation I am firm believer in the quote of Antoine de Saint-Exupery:

“A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.”

As I see it there are a few main purposes of producing documentation:

To convey understanding - This shows my quite liberal view of documentation since I consider drawings on a white board or a napkin to be documentation. But I also consider this to be one of the most important purposes of documenting things. From a designer’s viewpoint these “documents” are vital in going from an inner vision to an operational image that can be shared by others. Common examples of documentation conveying understanding in large organisations are presentations given at various meetings. These documents can be saved for posterity, but the ability to convey understanding is much smaller for those who weren’t there. On the other hand are written documents one of the most efficient means through history to build on knowledge of others which you never had the opportunity to meet.

To formalise agreements – If there is a business agreement between two organisations it is almost inevitable not to have a more formal document detailing the technical content of the agreement, the specification. many organisations, including my own, also use documents to formalise the agreement between internal teams. Your mileage may vary how efficient this is in various organisation.

To preserve information – The human memory is not infallible. Documentation is a great support to minimise the decay that is inevitable when only relying on the human mind. Software is also about maintenance and any body who has been given the responsibility to update legacy code that is undocumented know how difficult it is (this scenario includes the purpose of understanding as well)

I don’t buy “the code is the documentation” at all. The code by itself does not fulfil any of the purposes above.

I have recently worked in a project which solely relied on Trac to capture all information relevant to the project (except finances). I am positively surprised how much you can achieve with so little formal documentation in combination with having everything in the same place available for everybody in the project. I will try to do a more formal evaluation according to the purposes above when the project is near it’s end.

When to decide?

I have recently experienced several occasions where people want to decide things as early as possible in a project. This seems to be based on previous experiences that this was difficult in the last project and we want to eliminate things to worry about late in the project since there will be new things to worry about then anyway. So why not solve the major problems you are aware about anyway?

I think this kind of thinking is detrimental for the success of the project, especially if the decision influences the architecture (Grady Booch said something like "the architectural decisions are those costly to change").
If one looks at the reason the problems came up in the first place it is usually things like the implications (especially technical) of the decisions was not fully understood, the requirements were not suitable, or my personal nightmare that my team will not suffer any consequences whatever the outcome so why not decide this now...

If one has superficial understanding of the consequences or if the requirements are unstable it is a better strategy to postpone the decision as late as possible, and also delegate it to those who are most affected/concerned. But this means you and your organisation is comfortable with living with uncertainty. Which may be very difficult depending on the culture or the organisation. For example if all of your project revolves around a stage-gate process (very common in the automotive industry) it really does not fly well to say "let's postpone this decision for another 6 months and make progress with what we can".

It may sound I ampreaching the agility gospel, but that is not the case. I have full understanding that once you have made an architectural decision you don't want to change it. I just want to argue for the heuristic that you should not decide something because you can, postpone it to when you have make it.
And as a consequence I really dislike when you have to decide things just to feed the process, especially if the process is very slow to change.