Clean Code Notes — Chapter 4: Comments
Introduction
Comments are not inherently good and should be seen as a necessary evil. The code should be self-explanatory, making comments less necessary.
Don’t comment bad code — rewrite it
This famous quote, reinforces the idea that writing clean, clear code should be the priority. If code is expressive enough, comments are not needed. Comments often indicate that the code fails to fully express itself, and using them can be viewed as a failure to communicate effectively through the code itself.
One of the major drawbacks of comments is that they can become outdated, especially as code evolves. When code changes, comments may not be updated, leading to misinformation. These outdated comments can mislead developers and create confusion, making them worse than having no comments at all. The passage provides an example of how comments can become separated from the code they were meant to describe, leading to inaccuracies.
Comments can lie as they age, while the code itself remains the only truly reliable source of information. Focusing on writing clear, maintainable code to reduce the need for comments. When comments are necessary, they should be maintained carefully, but it’s preferable to invest energy in making the code expressive enough to minimize the need for comments altogether.
Good Comments
Comments are generally undesirable, but there are some types of comments can be useful. However, even these should be minimized or avoided when possible. Good comments are categorized in the book as follows:
Legal Comments: Legal or copyright comments are necessary for corporate or legal reasons. These comments often appear at the beginning of source files and can be hidden by an IDE to prevent clutter. For example, copyright statements or licensing information should be included but kept concise.
Informative Comments: These provide basic information that might not be clear from the code itself. For instance, a comment explaining regular expressions to clarify their purpose might be usefull. However, moving complex logic to a class with a descriptive name might eliminate the need for comments.
Explanation of Intent: Sometimes, it’s useful to explain the reasoning behind a specific decision in the code. This kind of comment provides insight into why a particular solution was chosen. For example, when sorting objects, a comment explaining why a certain class is ranked higher than others can help future developers understand the rationale behind the implementation.
Clarification Comments: These comments help clarify obscure code, such as argument values or return values from standard libraries that can’t be changed. Though clarifying comments carry the risk of becoming outdated, they can still be useful when altering the underlying code isn’t possible. If you have ability to refactor the code it is encouraged to refactor the code rather than commenting on it.
Warning of Consequences: Warning comments are useful for alerting developers to potential issues. For example, a comment might warn that a test case takes a long time to run. Such comments can prevent misunderstandings or mistakes when others work with the code.
TODO Comments: TODO comments are placeholders for tasks that still need to be done but can’t be addressed immediately. These notes serve as reminders but should be removed once the task is complete. Although TODOs are easy to track in modern IDEs, they should not be overused or left to accumulate in the codebase.
Amplification Comments: Some comments highlight the importance of minor details in the code that might otherwise seem insignificant. For example, trimming whitespace in a string might seem trivial, but a comment explaining its importance ensures that future developers don’t overlook it.
Javadocs in Public APIs: For public APIs, well-written Javadocs are essential to provide clear and accurate documentation. However, like other comments, Javadocs should be written carefully to avoid misleading or outdated information.
There are instances where comments are useful, they should be used sparingly and with caution. The best comments are those that you find a way not to write by making your code clear and self-explanatory.
Bad Comments
Comments in code often serve as outcome of poor coding practices or insufficient decisions, leading to confusion and miscommunication. Instead of adding clarity, these comments can obscure the code’s intent, making it harder to understand and maintain.
Mumbling Comments: These comments are unclear and leave the reader guessing about the actual behavior of the code. An instance of this would be a vague comment in a catch block that doesn’t clearly explain what happens when an exception is caught.
Redundant Comments: Adding no new information and simply repeat what the code already makes clear. Consider a comment that describes a method’s functionality in the same way the code does.
Misleading Comments: They provide inaccurate information, potentially leading to misunderstandings. Imagine a comment that incorrectly states when a method will return.
Mandated Comments: Clutter the code without adding meaningful documentation. This can be seen in required Javadoc comments for every method and variable, regardless of necessity.
Journal Comments: These can become excessive and are often redundant with modern version control systems. Think of a log of changes made to the code at the top of a module.
Noise Comments: They provide no additional value and simply restate what the code already clearly indicates. An example would be comments that state the obvious, such as “Default constructor” or “Returns the day of the month.”
Conclusion
Comments can sometimes be necessary, they are often a sign of unclear code and can lead to confusion and misinformation if not maintained properly. The focus should be on writing clear, self-explanatory code that minimizes the need for comments. When comments are used, they should be precise, informative, and kept up-to-date to ensure they add value rather than detract from the code’s clarity.
If you find this article interesting, kindly consider liking and sharing it with others, allowing more people to come across it.
If you’re curious about technology and software development, I invite you to explore my other articles. You’ll find a range of topics that delve into the world of coding, app creation, and the latest tech trends. Whether you’re a seasoned developer or just starting, there’s something here for everyone.
References
Robert C. Martin. 2008. Clean Code: A Handbook of Agile Software Craftsmanship (1st. ed.). Prentice Hall PTR, USA.
