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:

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?

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.