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
Mark Smith
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.
Edwin Torres
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.
Rodney Bates
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.
Edwin Torres
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.
Hugues Ferland
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.
Edwin Torres
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.
Steve Fouracre
There are many additional reasons to use comments. Here are a few.
1. It allows an easy way of linking the code directly to the requirements written as Stories in agile. So lets say you are using a popular ALM tool like Jira to capture requirements it is important to link the code directly to the Story and if the Jira Id is say PROJA-001 simply enter this unique Id as a comment into the code and now the reader can find the exact Story that was responsible for the code
2. I use Salesforce and in any cloud system there are limits on everything and 1 limit is the length of the function declaration and therefore this can prohibit the alternative approach of commenting by code. Also codebase length is limited but comments are not limited and so having longer function declarations causes issues on this 2nd limit in Salesforce
3. Often functions do need extra detail and can be impossible to simply make self explanatory every time and for those who say the opposite haven't built complex systems. I agree to use comments where appropriate eg: dont tell me this is a for loop, even my grandma knows that; but do tell me why you are making a callout to a downstream system
Steve Fouracre
Regarding Edwins comment on March 07, 2018 10:31 I agree and I try very hard whilst Im writing code to simultaneously think of the reader at various levels, an art that can only be mastered with time and effort. But I simply ask myself as Im writing how complex is this that Im writing and if I gauge over a 5 score (1 to 10) then it may warrant a comment. So when Ive completed the block of code or function I read it again to myself which identifies any bugs but also I then identify where I should place a comment. When Ive made the comment, I read it back to myself to make sure it makes sense.
This is the process all good developers should adopt in my opinion
Steve Fouracre
Our brains are conditioned to reading in a certain way and simply including spaces speed up our brains processing (https://www.sciencedaily.com/releases/2011/11/111128171220.htm). Therefore our brains can process the 1st function below far faster than the 2nd method. Not because there are fewer characters, which there are more characters in the 1st method, but because of how our brains interpret the data:
//create invoice for Expired, Cancelled and Cleared type Contracts, email the invoice to customer and create a Task for Finance
createInvoicesForContracts()
createInvoicesForExpiredAndCancelledAndClearedContractsCreateFinanceTaskAndEmailCustomer()
CACM Administrator
Steve- thank you for your insightful responses. It reinforces the importance of including comments in our code.
Displaying comments 11 - 20 of 20 in total