The Only Type of Documentation That Matters

There is a particular kind of silence that exists only in front of old code. It is the silence of a detective standing at a crime scene where the victim, the weapon, and the motive have all politely agreed to say nothing. The code works. The code has been working, quietly and without complaint, for three years. And now you, armed with the finest tools modern civilization has to offer — which is to say, git blame and a cup of coffee gone cold — must determine why anyone thought this was a good idea.

This is the great secret of documentation, which every programmer discovers eventually: you will not forget what the code does. You wrote it. It is right there, in a language you understand. Given enough time and a sufficiently stubborn refusal to go home, you can read almost any code and work out what it is doing.

What you will forget eventually and won’t be able to remember is why.

Why is the timeout 37 seconds and not 30. Why does this function check for negative numbers when the input, according to the type system, several meetings, and a signed affidavit, cannot possibly be negative. Why is there a comment that simply says // do not remove, left by someone who has since moved to another company and possibly another continent.

Comments that explain what is written are a polite lie told to the next programmer. The code already says what. It is required by computer laws to say exactly what it does, otherwise it wouldn’t run.

So please, please, please write down the why. Do not repeat yourself. DRY!