Traditional software wisdom tells developers to comment on their code, but modern development movements like Clean Code suggest that if you need comments, your code isn’t expressive enough to get your intent across.
To comment or not to comment the code? That is the question. Traditional software wisdom strongly suggests that developers comment their code. In fact, if you look at most code metrics analyzers, they will offer a feedback ratio metric that can be used to get an idea of the “quality” of the code documentation. (In my experience, most code has a ratio of less than one. Comments ratio = Lines of comments / Lines of code.) However, modern development movements like Clean Code suggest that if you need to comment your code, your code needs to be rewritten because if you need a comment, your code isn’t expressive enough to convey your intent. So, should we comment on our code or not?
Comments are a tricky subject for several important reasons. First, it’s not uncommon to come across a comment block that’s out of date with the code it’s supposed to describe. A developer may be in a hurry to release a feature due to a deadline. The developer can quickly update the code, commit it with the intent to go back and fix the comment block later, only to be pulled into the next fire. Over time, the comments don’t match the intent of the codes. (I would say this is a matter of discipline and professionalism. Developers should do all the work properly, which includes updating their comments when the code changes.)
Second, comments are often repeated without adding value to the code. When this happens, it’s easy to see comments as clutter and just get in the way of the code. Large comment blocks can also often be viewed as simply cluttering the code. However, I think with today’s modern IDEs this is more of a problem than a real problem. We can hide comment blocks and seamlessly navigate large code bases. I’ve found that comments generally don’t cloud my ability to navigate and understand code.
Finally, the real problem with comments is that they can be a crutch for writing poor code. The code should be expressive enough that anyone can simply read it and understand the developer’s intent. Yes, sometimes additional comments can help give context and useful background information. In fact, sometimes when an implementation can go in two directions, it is useful to explain why route A was taken over route B. Usually such things involve managing business risk or improving performance , scalability, maintainability, etc. However, using comments to try to elucidate poorly written code is not good practice.
Despite these lingering issues, feedback can bring additional clarity and understanding to developers that might not otherwise be there. Carefully crafted and purposefully constructed comments should not be avoided, they should be encouraged.
Here are some of my personal commenting best practices:
- Write code to express intent so that if comments aren’t present, the code is still clear
- Use Doxygen markup and templates to document public or customer-facing modules. Doxygen comments and markup can seem to clutter the code and add the extra need to maintain comment blocks. My experience is that the clutter is a minor annoyance compared to the value provided by the generated documentation.
- Take advantage of the IDE’s ability to hide comment blocks if needed.
- Spend 30 seconds reviewing and updating comments for any changed functions, then move on. (Functions should be small and single-purpose. More than 30 seconds tells you there are other problems in the code).
- Limit large blocks of general comments by referencing the development wiki or other external sources for clarity.
Commenting code has standard practices that we can adopt across the industry, but there are also modern practices that are personal preferences and pet peeves. As a developer or team, you need to decide which best practices work best for you. Once you identify them, be disciplined and stick with them. Review them every year to make sure they still make sense.
Do you comment your code? What best practices do you follow?
|Jacob Beningo is an embedded software consultant specializing in real-time systems based on microcontrollers. He actively promotes software best practices through numerous articles, blogs, and webinars on topics such as software architecture design, integrated DevOps, and implementation techniques. Jacob has 20 years of experience in the field and holds three degrees, including a Masters in Engineering from the University of Michigan.|
For more embedded, subscribe to Embedded’s weekly newsletter.