Why Code Comments Still Matter

I originally posted this article at BLOG@CACM.

In computer science, you are taught to comment your code. When you learn a new language, you learn the syntax for a comment in that language. Although the compiler or interpreter ignores all comments in a program, comments are valuable. However, there is a recent viewpoint that commenting code is bad, and that you should avoid all comments in your programs. In the 2013 article entitled No Comment: Why Commenting Code Is Still a Bad Idea, Peter Vogel continued this discussion.

Those who believe that commenting code is a bad idea argue that comments add unnecessary maintenance. When code changes, you must also modify comments to keep them in sync with the code. They argue that it is the responsibility of the programmer to write really obvious code, thus eliminating the need for comments. Although these are valid reasons to avoid commenting code, the arguments are simplistic and general. Comments are necessary for a variety of reasons:

1. Not all programmers can/will write really obvious code. Beginning programmers are just happy to write a correct program. They are still mastering the craft. Even experienced programmers write sloppy code, sometimes due to laziness (I have been guilty of this). Programs are unique like fingerprints, so judging whether code is obvious is a subjective call.

2. It can be overwhelming and tedious to comment too much, but some comments are like titles and subtitles in articles. They guide you, provide context, and convey an overall meaning.

3. Comments are not just for code. They can document important program information such as author, date, license, and copyright details.

4. Some programming languages are cryptic. One example is the Glass programming language. This sample program is hard to decipher, but it prints a Fibonacci sequence. Is the meaning of this program clear to you? It may be possible to write this program in a more obvious way, but a simple comment at the top of the program would convey its meaning quickly and easily.

5. Some companies require their employees to comment their code. Google has programming style guides that specify how to write comments. This includes popular programming languages like Java, JavaScript, and C++.

6. Specialized comments allow tools like javadoc, JSDoc, and apiDoc to automatically generate professional, thorough, and consistent documentation for programs.

7. Comments can be placeholders for future work. This is a useful way to create an outline for a large program. In fact, the Eclipse Integrated Development Environment (IDE) automatically creates a TODO comment when it generates a main method. This is a reminder to add the starting code of a program.

There are many important reasons to comment your programs. Although commenting may be tedious or overwhelming, it is valuable in many situations. Even if you think you write really obvious code, try reading your code months or years later. Will it still obvious to you, or would you wish for comments?

Thanks for reading. 😃

Follow me on Twitter @realEdwinTorres for more programming tips and help.

_{^{Photo credit: Gabor Heja, link}}

Comments

[Eljay-Adobe]

At the other extreme end of the spectrum is Donald Knuth's Literate Programming.

Where the code is embedded the equivalent of a giant comment (i.e., the documentation, requirements, specification, acceptance criteria, and other explanatory prose). Since this is from Donald Knuth, I rather expect that the document itself is in TeX.

I never worked with Literate Programming, but a co-worker of mine did extensively. Raymond Chen was a graduate student under Donald Knuth, and he got to experience Literate Programming personally for non-trivial projects.

Raymond's assessment was that the tooling for that style of programming was so poor, that it was practically unworkable.

He wasn't knocking Literate Programming; he was referring to the toolchains and debugging tools made it unbearable. That can be solved by better tools.

For me, good comments are useful, and are welcome. Bad comments are not useful, and I delete them.

A good comment explains WHY something is the way it is, HOW TO overview, or is a TODO.

A bad comment adds no value.

Because it is repeating what the code is doing, x = x + 1; // Increment x by one..

Or because the comment is incorrect, document.save(); // Load the document

Or because it could be made unnecessary by writing better code. int x = 0; // x is the person's age. --> int age = 0;

Or because the comments are scaffolding for when creating the code. Including pseudo-code. Once the code is created, the pseudo-code and "mini TODO" comments become unnecessary. And over time, the code will evolve making those comments incorrect. (My C++ project is 32 years old. There are a lot of those kinds of misleading comments.)

I think those kind of bad comments we can all agree are not useful. And, unfortunately, these are not contrived strawman examples.

Now if I was programming in Glass, I'd probably have a different take on comments. But I'll wait for Microsoft IronGlass#.NET before worrying about it. ;-)

[Edwin Torres]

Thanks Eljay-Adobe. Excellent discussion. Another thing I came across recently is the use of TODO comments. Apparently it is somewhat of a software security risk. We got flagged for that at work, although just LOW priority. To resolve them, just make sure to implement the code and remove the comment.

[Enrique Jose Padilla]

My 2 cents after reading Clean Code by Robert Martin and 2 years of experience.

TLDR: Minimize comments except for WHY questions.

Whenever i feel the urge to comment, I look at my code and try to think as if i never have seen it before. I generally have a checklist.

• Is my naming verbose and clear
• Am i mixing levels of abstraction in my function, can i make it smaller by breaking it up.
• Am i using magic numbers
• Will reading this comment allow the user to be more productive
• Is the comment tightly coupled to the LOC

There's probably a couple more, but those are top of my head.

100% i comment for WHY. These tend to be exceptions that at first glance seem wierd to anyone who didn't see when it broke.

[rhymes]

I tend to comment for the why more for the what. We read and maintain code far more than we write it so I lean on the why, it also helps in the life cycle of the comment itself. If you refactor the section below the comment, the comment itself can still be valid.

[Edwin Torres]

That's very true. As software developers, we spend a lot of time maintaining or enhancing existing code. I agree, comments can help there.

[Brad Ledford]

I always liked to start a program with comments as pseudo code or to do the same in a unit test. Collecting ones thoughts by writing the goals of the program in narrative form always helped me later in the implementation. Rather than deleting each step in the pseudo code, I would leave it in place just above each step in the code.

[Edwin Torres]

Brad- I take the same approach. Those comments are like an outline. I agree; why not leave them after implementation?

[Ben Halpern]

Probably a conversation that will never end because there is a lot of nuance. I'd definitely not back all the way into one corner or the other.

[Edwin Torres]

Ben- I agree. There's a time and place for comments. No need to deal in absolutes.

[Noki Doki]

1. If you’re being lazy or can’t find a clear way to write a piece of code, just put a comment instead, but self-explanatory code is still better ultimately

2. Meh, classes and methods do a much better job of providing an outline

3. Metadata is a special case, I don’t think anyone includes that in comments that “need to be banned” as it just can’t be replaced with better code

4. Lmao, who the hell actually uses that? I guess it falls back to point 1 where you can’t write clear code, but if you’re using joke languages like this, making your code hard to read is most likely the whole point anyway

5. Some companies require comments because they’re (considered) important, not the other way around, this doesn’t prove anything

6. Documentation kind of falls in the same case as metadata imo, it can’t be replaced by code, as its readers may not even have access to the code

7. Well yeah, code can’t really explain what code is yet to be written

Basically comments do have their uses, but they should be used sparingly (except documentation and metadata) to let code speak for itself.