[email protected]

Why Code Comments Still Matter

Edwin Torres

February 26, 2018

Some believe that commenting code is bad, but comments still matter in our programs.

User Comments


Hi Edwin,

I had a client once with the no-comment rule.

I could not read the client's code, even though it was quite well written, immediately killing the premise of the pure no-commenters.

The reason is simple: using English to elicit a mental map of the code within the entire codebase is crucial for quickly remembering where you want to make updates. Without this hint, the coder will be continually re-learning in an inefficient manner.

And in general, I believe this to be evidence of a general rule: some organizations would rather increase implicit labor cost than increase explicit code size. "Driving costs to the edge", they call this in the military.

I do quite agree with Peter, though, that using comments at the function/method level is sufficient almost all the time. I just need the mental map, not some potentially inaccurate re-hash of the logic.

Mark- Thanks for the comments. You summed it up well. There definitely is an implicit labor cost (inefficiency) regarding commenting, with both too few and too many comments.

I do a lot of maintenance of other people's code (and my own that I don't fully remember), and my commenting principles come mostly from the question "what would make this easier". The most important is "is it *locally* apparent to a competent coder in this language what is going on here". If so, a comment would provide minimal benefit, while still suffering from the usual problems of code cluttering and not being kept up-to-date. If not, a comment is called for.

By "locally", I mean you don't have to search out additional information from many far-flung places, especially if there are not easy direct paths to the relevant places.

As a simple example, when there is a subscript value being used to keep track of how much of an array is occupied with meaningful information, there are two common alternative invariants. Either the subscript points to the last occupied element, or the first unoccupied one. You could infer this from careful reading of any one use, if only you knew for certain that whatever the invariant is, it is followed consistently. When doing maintenance, you are asking for trouble if you make this tenuous assumption. If there is any doubt, to avoid fixes that induce more breakage, you must locate them all, and make them consistent if not already so. And once done, add a comment at the relevant declaration point, for the benefit of any poor wretch who should fall into this web again. It could be you.

This is even more important when the needed information is not even in the software system you are working on. Examples are a compiler that supports multiple target machine/OS combinations and a debugger that has to work with multiple compilers. Or just any imperfectly-documented library code. (Can you assume a perfectly-documented library exists?) Sometimes you have no control over these outside software systems, or even access to their source code.

I always modify or add comments documenting any information that was hard to dig out.

Rodney- Thanks for the insightful comment. Your example supports the notion that there is an art to providing good comments. I recently read comments that made me wonder if they were no longer valid. They were "TODO" comments, and I could not tell if the functionality was already implemented.

The topic on writing comments or not is very broad.
Comments can be badly written with reasons ranging from not mastered second language to missing maintenance.
Edwin, what do you think you could have done? How could you know, at the moment you wrote the code, what comment would help you in the future? I don't think it is an easy task to make the right decision. Too many things can change between the moment we write code and months or years later when we need to read the code.
If it is hard to write code that is easy to read, I think it is equally hard to write well structured comments that will not get in the way later. Plus, there is no way to proof the comment is correct other that by looking at it with the eyes of the future readers.
I also think we try to move too fast from beginner to seasoned programmer. If we could pair beginners and masters to help learn the craft then maybe we could improve our art - code and comments alike.

Hugues- You may very good points about writing and maintaining comments. I especially like your comment about moving from beginner to seasoned programmer. I agree with you. That is not something that can/should happen overnight. Only with time and practice can you become an advanced programmer. Thanks.