⇥ 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.
Let me make an example using an actual piece of code taken from a project I’m working on in an effort to avoid the hello-world syndrome that so often affects this kind of post:
function construct(array $pathInfo) {
$section = $pathInfo[0];
$file = $pathInfo[1];
// Assume that the location of this file is inside the main trunk, and that pathInfo has already been filtered.
$path = dirname(FILE) . '/../../' . $section . '/xml/static/' . $file . '.xml';
if (!file_exists($path)) {
Controller::singleton()->doError(404);
}
parent::construct('main/xsl/template.xsl', $path);
}
Now, as you can see this code contains only one comment, but I think that any reasonably competent developer would have no problem understanding what it does, because the code itself gives you all the assistance and hints you need. On the other hand, all sorts of big red WARNING flashing lights would be going on in a developer’s mind without the comment: why is the code looking for things using relatives paths? And, most disconcertingly, why isn’t the $pathInfo array being filtered before usage*?
Thus, the concept of “self-documenting” code is not a myth—code should be written so as to tell a developer what it does without the need for any comments. It is a myth insofar as people use it as an excuse to avoid documenting their intentions, which is really what comments are useful for.
* I cheated a bit here, because in the real codebase the filtering is done system-wide, so part of this comment is really superfluous if you know the codebase’s overall design, which, of course, would be documented elsewhere.
Comments
While I would still have had a few more comments in there …
(Because I want someone to be able to look at that function, without necessarily having 100% understanding of the ‘system’, and be able to know, in general, what some of those other calls are doing)
I do agree with you on the sentiment. The main point of comments inside the code is to explain the intention behind the code, which is not inherent in the code itself.
I have to agree with Eli. As a freelancer, when I am brought in to modify a system time is always of the essence. The more that comments can help me understand context, the easier it is for me to get up to speed.
The notion that the computer “gets it” is absurd since the computer will follow whatever instructions you give. As a developer, I have to understand the why of it, so I can give the computer the right instructions.
Well-written code makes it easy to understand what the computer is intended to do, but not always why the previous developer wanted the computer to do take that action.
Variable and class names operate in the domain of human language and are as susceptible to interpretation as any human communication. Good naming conventions reduce the chances of misinterpretation, they don’t eliminate it.
Yeah, gotta agree that comments help you understand context. The other day I ran into the same discussion with a fellow colleague who said that ‘good code needs no documentation’.
Most certainly, we all write different code. And ‘good code’ is of course not as subjective as one may think. At least there are obvious errors.
If people can read your code (which makes code ‘better’ for most developers) depends on experience and minors, such as: methods are in English — am I a decent English speaker (or reader)?
When I talked to my colleague, I stated that I wouldn’t document the obvious — e.g. in your case the file_exists(), etc.. But I’d document my methods and also the ‘flow’ where necessary.
He disagreed (of course).
So the obvious is not your dirname() — even though I know what that does — and also not quiet the call to the parent::__construct().
Point taken you can always argue — what is obvious and what is not.
The obvious is that you USE dirname() to build a path and you call the constructor of the parent class with two arguments.
Not so obvious is why you call the parent’s constructor and why you built a weird looking path in this constructor.
If you argue that it would be more obvious when I had the entire code. Well, IMHO that proves my case.
I find myself digging into code often. I’m doing code review and the like for clients I often think about appropriate documentation.
From what I learned the argument of documentation vs. none always boils down to the fact that of course a reasonable skilled developer can figure out the code by himself.
But should he have to? Most certainly not.
Cheers!
I agree here, well, I’d even go one step further and say that code that has too many comments is really hard to read and understand!
I’ve seen code with more than 75% comments. An extreme example, and I have to admit that I somehow enjoyed reading it as it was so weird.
Saying code doesn’t need any comments is very misleading. There are plenty of cases where one does something strange to achieve some goal. Maths and optimizations quickly come to mind.
I have seen people swap out every comment with detailed identifiers. This doesn’t help and, in fact, the code becomes more of chore to work with.
Going to either extreme in the never ending comment debate is counter-productive. It is better to find a nice balance between excessive, useless comments and no comments at all.