5 Rules for Comments to Doc You Out of Problems
Commenting on code can seem like a chore but documenting changes and their purpose is key to helping others understand your code.
Join the DZone community and get the full member experience.Join For Free
Overview: Commenting on code can seem like a chore, but documenting changes and their purpose is key to helping others understand your code. These five rules serve as a handy guideline to help you make the most of your comments and make sure they’re seen and understood by others.
Mention comments and documentation to a group of developers and you are likely to get a “heated discussion.” Documentation may be a good idea, but it is rarely ever done, let alone done right, and can never be expected to be fully up-to-date. When we get to comments, it seems to be more a matter of degree. We see the need, but how many should we put in and how much should we have to rely on them?
If you struggle with commenting, you are really struggling with your logic.
We suggest following these 5 simple rules to form a guideline for using comments.
- Your documentation should reside in your code, not outside. Having the documentation in the form of comments means that it travels with the code. There won’t be any hunting for it or questions about whether it is the latest comment. The only exception to this rule is when documentation on the usability of the software is written. This can reside outside the code, in the form of a Confluence page, development manual page, etc.
- Comment on the line close to the action. Comments need to be right where the code is. You shouldn’t place comments several lines above the relevant code and expect someone to find it or realize it is related. When an update is made on a line, if the comment is far away, the comment may not be seen and therefore not updated. Keeping the comments and lines together makes understanding the code faster, and the comments are more likely to be up-to-date. It is important to remember that Integrated Development Environments (IDEs) do not correlate comments with their corresponding code counterpart, hence why the location of the comments is important.
- If logic relates to another section of code, comment there to relate. Something in the section you are in may have an impact on another part of the code. You need to form a bridge to make the connection visible. Building-in impact analysis could actually point out problems with your code. If you feel the need for a lot of these comments, your structure could be bad. If your comments are trying to explain the code, then that simply signifies a need to refactor. If the code structure is already well established and refactoring cannot be done, it is important to comment on the way it should function when the refactoring is complete. This helps future developers understand why code smells exist.
- For automated testing, a general rule is to write comments in relation to what that test will do. If an automated test fails, then the individual in charge of maintaining these tests can use the comments to debug the primary process of the test and figure out what the issue is, minimizing the time to debug the issue. Comments give you the opportunity to search for keywords in the future and help you see where the code has deviated from the workflow of the given test, and whether the test case needs to be changed to reflect that. Write the general sense of what the test will do. Link your tests to the code, not the other way around.
- Pay as much attention to the comments as to the code. Don’t make comments an afterthought, don’t ignore them in code reviews, and, most importantly, continue to update them as the code continues to change.
It can be easy to overlook comments when you're concentrating on code, but they are important. Following these five rules can help you make the most of comments and treat them they way they should be treated – as an investment in the future.
Published at DZone with permission of Zyad Alyashae. See the original article here.
Opinions expressed by DZone contributors are their own.