The code is THE documentation

Yeah sure... Sleep tight and noone is gonna rock your boat, at least while you are sleeping in it.

This is a very luring statement. The reason it is so luring is that it is so obviously true. Or is it not? Doesn't the program do exactly what the code tells it too? So the code is THE one and only always up-to-date documentation of any program. Right?

It is so convincing that you just can't resist falling for it, especially when faced with an aficionado that passionately claims that she doesn't need to write comments as "extra" documentation, because the code is THE documentation, and since she obviously writes top quality code, comments are simply redundant. A waste of screen estate more or less. Useless clutter around the actual documentation.

Sorry to break the news boys and girls... The reality is somehow different.

The code is the imperfect translation into a programming language of the programmer’s imperfect understanding about what the program should do.

You can figure out the rest. The code is THE documentation of the programmer's imperfect language translation of an imperfect understanding. It documents how the programmer failed to code properly what he failed to understand properly.

Anyone still battling on the issue of whether the code is THE documentation and whether comments (in any form) are needed or not, most likely hasn’t worked on a big project (300+KLOC) long enough (5+ years) to figure things out for him/herself.

Life is so sweet when 90% of the time you fool around your own code. Everything is so simple, because everything is in your head. However once you start spending 50% of your time on pieces of code that other people wrote, pieces of code you have NEVER seen before, or pieces of your own code that you wrote 4 years ago and haven't glanced at since, then life is not as sweet.

When you read code you are not familiar with, then you are doing the reverse translation, from imperfect programming language to imperfect understanding about the program's intentions. This is tough. Some may be better at it than others, but trust me... without good comments it can be much more painful and error prone than it has to.

So please, make others' lives easier. Let them cherish your memory after you are gone and enjoy fixing the bugs in your code. Because you WILL be gone some day and your code WILL still have bugs that need fixing.

Enjoy,
Dimitris Staikos

Comments

[adamo]

I once read that documentation is a set of hypotheses to be tested and not a set of axioms to be trusted. I think that this brings even more light to what you are trying to show.