Introduction
You're probably thinking," what's new with comments?" and you'll be right to think that.
Often times, not much thought is put into writing a comment. They are mostly ignored and considered secondary(albeit as they should be) but this negligence has led many programmers into writing very awful comments.
for example:
In order to avoid writing comments like this, I have written this article to serve as a guide to writing better comments.
Here are some guides to writing better comments
- Avoid writing redundant comments
- Comments should be updated
- Do not excuse bad code with commenting
- Comments should not reference other codes
- Comments should be informative
- Comments could be used to provide links to original source code
- Comments should not be used for attribution
The rest of this article explains these guides and provides examples to them.
1. Avoid writing redundant comments
The above is common among early-beginners as they're introduced to code, While this could be very helpful with teaching beginners. Its considered redundant as it adds no information and merely causes visual clutter.
2. Comments should be updated.
Overtime comments silently degrade. While code is continuously updated, the comments are forgotten. For a code cryptic in nature, readers turn to the comments to provide an explanation, and when that explanation is false it leaves the readers confused or worse mislead.
for example:
The asterisks in the regex pattern show that it matches a whole lot more than it was stated by the comments which could be very misleading to the readers who do not bother to check the regex pattern.
3. Do not excuse bad code with commenting
Commenting should be used as a last resort. Every comment serves as a failure to express yourself clearly in code. Always try to clean the code to express yourself better before resulting to commenting.
for example the code snippet below could have been cleaned up rather than using a comment.
After cleaning it up
4. Comments should not reference other codes
A comment should not reference a code that is not present or local because the reference code could change but the comment wouldn't
for example
The comment above references a "default" that is not present in the code block, this confuses the reader as they don't know what default in the comment means.
5. Comments should be informative
The comment above informs the reader that SimpleDateFormat is not thread-safe, if the code is to be modified, the programmer would be well informed of its limitations.
6. Comments could be used to provide links to original source code
Readers can follow the link provided in the comments to learn more
7. Comments should not be used for attribution
Comments like these are unacceptable especially in production. The source code control systems can always tell who the author was.
Conclusion
I hope this article has been helpful in highlighting the importance of writing proper comments and the guides provided were well understood.
References: Clean code(A handbook of Agile Software Craftsmanship)
Top comments (3)
thank you so much i really enjoyed reading your post.
i also have a one thing to add, i think that the best way to write comment is by trying to not to write comments , and make your code self documenting, where our functions and variables speaks for it self.
we should only write comments when we can not write a self documenting code.
Lovely post
Awesome post