The myth of the myth of self-commenting code

Synchronicity! I was thinking of writing on this topic, and up pops this gem…

The Accidental Businessman wrote:

The myth of the myth of self-commenting code

On Code Commenting And Technical Debt | BrandonSavage.net

Interesting post by Brandon—I disagree only on one main point:

This myth of self-documenting code needs to be squashed once and for all. Commenting is important, and unless your code does nothing other than display “Hello World!” it’s going to need some explanation.

I find this view of coding a little misguided, to be honest—in fact, I would go as far as saying that code doesn't need any comments.

Wait, did I just say that? Yes, I did, and here's why: code is a discussion between the developer and a machine. Writing code that cannot be comprehended by another human being is a bit like writing a letter to your dear friend in a language you can write but not read—strange, at best.

Good code should be self-documenting insofar as you should be able to understand what the code does without the assistance of any comments—after all, the computer gets it, so why shouldn't you? This can easily be done by the judicious use of clear logic and good programming practices like giving your variables names that are actually related to what they do.

What I suspect Brandon really means is that the comments are there to illustrate the intentions of the author when those intentions are not immediately made obvious by the code itself. This, I daresay, is the crux of Eli's argument that commenting inside the code is the most important contribution that a developer can make towards eliminating technical debt. That's because commenting inside the code helps understand the reasoning behind the choices that were made when writing the code, rather than what the code itself accomplishes…

Having re-invested myself to production level coding, and having dug into lots of existing code bases over the years, I've come to a similar conclusion… comments in code are only necessary to explain choices that are otherwise not obvious.