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.
In order to avoid writing comments like this, I have written this article to serve as a guide 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.
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.
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.
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.
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.
A comment should not reference a code that is not present or local because the reference code could change but the comment wouldn't
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.
Comments like these are unacceptable especially in production. The source code control systems can always tell who the author was.
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)