Explain Dont Document

As I see it, commenting styles fall somewhere between two extremes.

Documenting: ("I have documented everything.")

Concerned with covering all the major observable facts about a program.
Terse and formal comments, evenly spread throughout the code.
On an abstraction level not far from the code.

Explaining: ("I have thoroughly explained the hard bits.")

Concerned with guiding the reader to an understanding of the program.
"One half of an imaginary dialog"; informal, narratory style.
Fewer, longer comments clustered around important or difficult code parts.
Often more high-level (see TheWhatButNotTheWhy).

A style I use (and yes, I still think comments are important, and I have found no end of bugs in my own code as I write them to rationalize what the code is doing) is to go back, when I think the code is right, and add a narrative, paragraph-style comments down the right hand "margin" of the code. It's no bother to add them, but changing the code upsets the comments, so it does force the comments to be updated when the code changes. It makes be think just a bit harder about the code before I add the comments the first time, to try to avoid subsequent updates to the comments.

When I find that I have misunderstood something about the code I'm working on, then I know that something needs to change.

Given the general lack of testability of the legacy systems I encounter, I start with adding comments, then changing variable names, function names, and once I have a better idea of what's going on, refactoring. Any point at which I can't easily understand and explain what the code is doing, and possibly how and why, serves as a trigger that I should change things so that anyone (including me ;-) can better understand the what, how and why of the code.

I keep asking myself "how do I know, without running it, that this code is correct?"

(Of course, if these legacy systems had decent unit tests, I could just run them, and I'd know it's correct.) -- JeffGrigg

This seems to be close to FaqAsDocumentation. See AppropriateTechnicalDocumentation and FrequentlyAskedQuestions, too.

DocumentationPatterns