Documenting Code

I have often heard "Code is the best form of documentation there is". To some extent, I believed that to be the gospel truth when I was younger. In the past several years of reading other people's code and observing other people read my code, I no longer think that statement paints the complete picture.

As developers, our goal is indeed writing code that can be easily understood and maintained. Maintaining code could mean either fixing bugs in the existing code or extending the functionality without extensive re-writes.

If there was a choice between writing this type of "clean code" and writing trick filled fancy code, we choose the former. To invoke Brian Kernighan (from The Elements of Programming Style)

Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?

However, writing "clean code" should not be a free-pass to do away with all forms of documentation.

What qualifies as good documentation?

The idea of documenting code is not about describing the code ("this line checks if the integer is 0" or "execute this loop 50 times"). This type of documentation is not particularly useful for anyone that can already read the code and (hopefully?) understand it.

I belive good documentation is one which describes the "meta" behind the code. Why was this logic written? What assumptions were made? Is there a corner case this code was meant to fix? How would this code scale?

Eventhough it is straightforward to grasp "how and what" a piece of code does just by reading it, the "why" is usually the hardest to understand and I think the easiest to document for a person that wrote the code.