Communications of the ACM
Why Code Comments Still Matter
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:
- 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.
- 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.
- Comments are not just for code. They can document important program information such as author, date, license, and copyright details.
- 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.
- 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++.
- Specialized comments allow tools like javadoc, JSDoc, and apiDoc to automatically generate professional, thorough, and consistent documentation for programs.
- 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?
Edwin Torres is a full-time software engineer at The MITRE Corporation and an adjunct professor of computer science at Monmouth University. Follow Edwin on Twitter @realEdwinTorres.
Comments
Dennis Hamilton
I think a key characteristic of comments is with respect to narration, as Ward Cunningham has pointed out. It can be important to distinguish what the code is *for*, not just what it is, and what the key assumptions and constraints might be. It is valuable to develop a grasp for what the requirements are and the code is rarely a substitute for that.
Edwin Torres
Dennis- That is a good point, and thank your for the citation. There are times when you just need a quick overview of the code, without spending time to trace through it. Comments help here, assuming they are correct.
Peter Vogel
Hey! Thanks for the mention.
There are many things we agree on -- I should, for example, point out that my objection is to comments "in" code. My objection is not to comments at, for example, the start of a method. Those are the comments that include (as you point out) the name of the author, date created, and so on (though, often, source control can automate that work).
I also definitely agree with you that code at the start of a method should describe what the method is "for" -- why the method exists or was written. This is something that even really obvious code can often not communicate. At best really obvious code can communicate the "how" of what the code does (though, the name of the method can sometimes help address what this code is "for").
We will even agree about the need to comment cryptic code. I will, however, suggest that the problem should not be first addressed by writing a comment: It should be first addressed by writing obvious code. If there is a bug in that Fibonacci generator or there's a need to enhance it, clear code will help you find the bug or enhance the code in a way that a comment can not. I suggest we consider a comment, in this scenario, as an apology from the original programmer to the next one: "I did the best I could but, for various reasons, I still ended up with this unfortunate code. Here's what I can do to help."
I like, especially, the idea of comments as headings and subtitles to guide a programmer through the code. I think, as a part-time technical writer, that especially appeals to me. Of course, I'm going to suggest that those comments are (like headings) be only two or three words in length...and, perhaps, evidence that this method should be refactored into several methods with their names reflecting those titles. But, in many cases, I can see that being overkill.
In fact, I will disagree with you in only one place: The idea that a programmer who can't write obvious code is, for some reason, capable of writing a comment that is (a) obvious, (b) accurate, and (c) complete. We hire programmers, after all, for their ability to write code, not for their ability as technical writers. And if the comment isn't accurate...well, to paraphrase "The Elements of Programming Style," the code and its comments provide two descriptions of the processing logic. If they disagree, only the code is true. At this point, code that goes beyond describing what a method is for creates a maintenance burden of fixing the comments to keep them in line with the code. Programmers are busy enough.
Again, thanks for the mention!
Graham Lee
That's a great list of reasons to comment, to which I would add one more: what is obvious to *you*, the author of the code, probably isn't obvious to *me*, the reader. If you've been working on the feature you are building for the last week, you have spent that week building a mental model of that area of the problem domain and its mapping onto the software system. I do not have that model. Developers should try to empathise with the developer who understands software, but is new to *this problem*, and help improve their understanding.
Edwin Torres
Peter- Thank you for the thoughtful and thorough response. I did enjoy your article and agreed with many of your points. My goal was to highlight some additional needs for comments. I 100% agree with you that the "code doesn't lie". Also, too many comments can be overwhelming and distracting. I find it interesting that a discussion on comments even exists today. Who would've thought?
Edwin Torres
Graham- Great point. One of my earliest lessons in programming is that it is much harder to change someone else's program than create your own. When used effectively, comments can help here.
Peter Vogel
Edwin Torres: You have no idea of the irony involved -- My article on why comments are a bad idea still holds the record for attracting the most comments of any article I've written.
CACM Administrator
Peter Vogel: That's really funny. Who knew that an innocuous code construct could cause so much discussion?
Robert Van Cleave
"Even if you think you write really obvious code, try reading your code months or years later" really struck home with me. I had to do a major revision to code I had written years earlier (without comments) and was totally lost at first. Once I got my "bearings" the code was obvious, but a few comments here and there at the beginning of some functions would have been a great help.
Edwin Torres
Robert- Exactly. That happened to me as well. I remember writing some code quickly and easily. But when I had to modify it a year later, I was lost. It was shocking. Like you, I got my bearings and made the change. But the initial ramp-up time could've been avoided with some helpful comments.
Displaying comments 1 - 10 of 20 in total