On Code Commenting And Technical Debt

If you’ve been in development for any length of time, you’ve probably come across a project or a company that doesn’t take the time to incorporate comments into its code. The argument is often made that “our code is self-documenting” and that commenting is just a waste of time, especially if you write clear, clean code. But I disagree.

Some people take a different view of commenting than others. Most recently, Eli White wrote an article called “Commenting on Commenting” in which he argued for commenting virtually every single line of code. He talked about working for a company where they stripped the code out and turned the comments into line-by-line documentation. But commenting to me is important for a different reason:

Failure to comment is simply the accrual of technical debt.

Technical debt is the cost of fixing things that you didn’t fix at a particular point because it would have been too costly. This cost can be in time or money, but represents additional effort that must be made. How does this apply to commenting?

Assume it takes one additional hour per file to write clear, complete comments. To save that hour now, you do not comment your code (before or after you write it), delivering the product faster. However, the next developer to come along and work on that code is going to have to learn about it. Assuming that it would take them an hour to learn about it with comments, and four hours to learn about it without comments, the two hours you saved by not commenting (the hour to comment, and the hour to read them) has cost you four hours of a developer relearning your code, for a total cost of 2 extra hours.

This clearly isn’t worth it.

Undoubtedly somewhere out there someone is going to say something like “wait a minute, Brandon! What if it takes less time?” If it actually takes less time, fine. You got lucky. Think back on your prior experiences, though. The cleanest code you’ve ever seen written by somebody else – how long did it take you to learn? The problem comes not because we write bad code or are sloppy in our design. It comes because we’re human beings and we have to understand the logic before we can modify it. It’s the same reason a doctor who specializes in the heart must understand the other body systems before he can do surgery – even if he never treats any other organs, he must understand how they work together. In the same way, a programmer must understand the logic behind code before they can modify it, and failure to adequately justify your architecture incurs a cost.

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.

Marco Tabini, a man I deeply respect, posted a rebuttal to my argument here. I recommend you read it, as he made some really great points.

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

David Marrs wrote at 4/30/2009 8:15 am:

Here’s my effort to further perpetuate that myth:

What happens when the comment doesn’t match the code? Is the code wrong or the comment? If you’re talking about understanding code, the only way you can truely do that is by reading it. A comment is only as useful as it is accurate and usually it’s not the glaring differences that are hardest to spot, it’s the really subtle ones. So if you’ve got to read the code anyway, you might as well make it readable. Viz. the code should be self-documenting.

I include comments to avoid ambiguities, like /* This line is duplicated here for a reason: don’t remove it. */. In a real example I’d explain what that reason is.

I also use them to point out where I think a weakness in the code (read: source of bugs) may occur, or where I’ve had to make comprismises. In short, comments are used to prop up weak code. The better the code is, the fewer comments it should require.

The worst kind of code to read is API code, which always has a big header above every function describing its signature and purpose. It’s great for the documentation parser, but not so much fun for the human trying to read the code.

Brandon Savage (@brandonsavage) wrote at 4/30/2009 9:16 am:

I think an obvious solution to comments being wrong is to expect your developers to update the documentation as they write new code and then enforce that. You must also give them the time to do so.

From a practical standpoint, I don’t think faster delivery of a product constitutes a good reason to skimp on documentation or commenting where such is warranted. And, if you use evidence-based scheduling (http://joelonsoftware.com/items/2007/10/26.html) the time required to document and develop should actually end up inside your estimate of a ship date anyway.

Large block comments can be collapsed by most modern editors, so I’m not entirely convinced that block comments are bad for humans. If you use vim or something similar this might be an issue, but I’ve found that collapsing the comment is often the way to make the code more readable, once I understand what it’s supposed to do.

Keith Casey (@CaseySoftware) wrote at 4/30/2009 9:47 am:

One thing that is missing from your analysis but would tend to support it is the software lifecycle itself.

Depending on who you listen to, the development process itself is only 10-50% of the lifetime of that code. The rest of the time spent on it will be maintenance… quite often not done by you. So while you may be unlikely to see the longterm benefits of commenting, the people following after you will. And since you’re likely to follow after someone else elsewhere, it’s a handy process to start and share.

Keep it up Brandon.

Brandon Savage (@brandonsavage) wrote at 4/30/2009 9:53 am:

That’s a really great point, Keith. And one worth noting.

In my professional experience I’ve only been the originator of a project once – that is, the person who started writing the first code for any given project. That means that all my other projects were written by other people, even if I was adding new code. I wanted to avoid personal anecdote in the blog posting, but this is something I’ve experienced first hand. It’s critical that a code base have a good set of documentation for those who come after.

Someone once said “code as if the next guy to maintain your code is a homicidal maniac who knows where you live.” I think it’s a good rule to live by.

Keith Casey (@CaseySoftware) wrote at 4/30/2009 9:57 am:

Actually, you bump into another good point that I’ve written on… peer pressure.

If the system is well-documented when you get there, I *suspect* (aka no evidence to support this) that later developers will be a little more careful and respectful of the comments that are there, hopefully adding their own. After all, few people want to be the guy that screwed things up.

And I’ve been meaning to write on that quote for months…. alas. ;)

Tom wrote at 4/30/2009 10:17 am:

Amen!

I have decided to not work with ppl that do not document their code.

I had the pleasure to work with ppl who argued exactly like you said: we have speaking method names and the code explains itself. I was new to the programming language they used and I had a hard time figuring out what they were doing.

But then again, I had the pleasure to work with ppl who appreciate comments. A former employer mailed me just recently. They had to tweak something in an app that I wrote for them years ago. The employer said it was breeze thanks to my documentation.

David Marrs wrote at 4/30/2009 12:27 pm:

Brandon Savage:
“I think an obvious solution to comments being wrong is to expect your developers to update the documentation as they write new code and then enforce that. You must also give them the time to do so.”

That’s reasonable enough except developers make mistakes from time to time, get distracted by the telephone, or whatever, and now we have a disagreement between the code and the comment. This is the worst kind of bug. Most bugs are easy to solve; this kind isn’t.

I’m not saying that code shouldn’t have comments in, but code *should* be self-documenting, and in my experience, all the best code is.

Here’s a link to one of my favourite examples of good code: very few comments, but very easy to grok.

https://sauerbraten.svn.sourceforge.net/svnroot/sauerbraten/src

Jay Pipes (@jaypipes) wrote at 5/1/2009 12:48 am:

David,

Hmmm, I think the code at the link you shown is poor. It’s all in C+ (note, not C++). Basically, it’s C-code masquerading as C++. If you code in C++, I say, use C++ idioms and learn how to code in C++ properly, not just in C with a couple object-orientated things floating around…

As for “self-documenting” code…well, here is a piece of the streams.cpp file:

https://sauerbraten.svn.sourceforge.net/svnroot/sauerbraten/src/shared/stream.cpp

void finishwriting()
{
if(!writing) return;
for(;;)
{
int err = zfile.avail_out > 0 ? deflate(&zfile, Z_FINISH) : Z_OK;
if(err != Z_OK && err != Z_STREAM_END) break;
flush();
if(err == Z_STREAM_END) break;
}
uchar trailer[8] =
{
crc&0xFF, (crc>>8)&0xFF, (crc>>16)&0xFF, (crc>>24)&0xFF,
zfile.total_in&0xFF, (zfile.total_in>>8)&0xFF, (zfile.total_in>>16)&0xFF, (zfile.total_in>>24)&0xFF
};
file->write(trailer, sizeof(trailer));
}

Yeah, completely clear and self-documenting. Not.

Tibo Beijen (@TBeijen) wrote at 5/5/2009 8:22 am:

Code readability imho is improved by both good commenting and meaningful variable and method names. Comments should best focus on the ‘why’, clear code can take care of most of the ‘what’.

Commenting (in my experience) can help in determining what has to be done, like explaining a problem to a coworker can help in seeing the solution yourself. I think (I hope) most developers think first and then start coding. Writing comments can take place right in between. Not doing so but finding time to argue why comments aren’t neccessary to me seem a bit odd…

Paul wrote at 10/29/2009 7:21 am:

Read Clean Code by Uncle Bob Martin and then you will realise that comments are just there to disguise bad programming!!!

Brandon Savage (@brandonsavage) wrote at 10/29/2009 8:51 am:

I’ll give the book a read but I’m skeptical that writing comments indicates bad code.

Copyright © 2023 by Brandon Savage. All rights reserved.