Brush your code after every meal

Programmers have many pet hates -- hardware and software being just two of them. There is however a bewildering paradox that I would like to talk about today. It is the anguish of documenting your own code on the one hand and the torture of having to use someone else's undocumented code on the other. Actually there is one thing worse than not having documentation. That is bad or outdated documentation and the world of open source software is rife with it. Old docs are like an old copy of the Lonely Planet where you travel half a day to visit some must-see haunt only to find out it closes on Sundays.

To many programmers writing source documentation is up there with cleaning the rim of the toilet bowl in terms of satisfaction. It shouldn't be like that if these people took a more selfish approach. Taking your documentation seriously is not for the good of mankind. It's all about doing yourself a favour in the end.

Source documentation is different from functional requirements and specifications in terms of the intended audience: it is written by techies to be read by techies. It is also different from other technical documents such as UML diagrams in terms of its purpose. Requirements and specifications describe what the software should do, whereas source documentation describes what the system actually does. As a consequence it is impossible to document beforehand what some class or method does before you have coded and run it. If you do document beforehand you'll need to check carefully that what you have coded is in line with your documentation, otherwise your carefully crafted text is instantly useless. And we already know that bad documentation is worse than none at all.

There is another good reason why you should document after coding. The writing of a piece of software is a fluid process, especially in the early stages. Over a short period of time you will throw away some classes, split them up, merge them and add or remove arguments. The less functional requirements you have, the more this will be the case. All the while you keep a clear mental image of the whole, and once you're satisfied you go over it again and describe exactly what you have done. In an ideal world, that is.

The satisfaction of seeing your own code work makes you hungry to write more. Why should I write down what happens when I can see what happens? Try to resist the urge to steam ahead. Take a step back, revise what you have written and describe it. More often than not you'll spot a bug or two in the process. More importantly though, all those classes and their interrelations make perfect sense in your brain now, but won't in year's time. Pay back your technical debt now before the interest eats up your team's budget. If you don't care for your employer's money at least protect your own future sanity. For those still unconvinced let me make it clear with a little dental metaphor. Brushing your teeth is not as much fun as the meal that preceded it, but nothing compared to the agony and expense this poor man went through:

Next week I'll share with you a way to make documentation more efficient and less of a chore. I have called it 'the duh test' – if that's too juvenile or American to your taste you may call it the “Well, obviously, my dear fellow” test. Whenever you feel you could stick a duh behind your comments, leave it out altogether. Documentation is about stating the non-obvious.