After describing where you need to use comments in part 1 of the article, part 2 would look at where to never put comments in your code. The idea of bad comments is what this article looks at. So below are some really bad ways of writing comments
- Codes that do not convey meaning to anyone beyond the developer who wrote the comment. A comment that does not explain to another programmer its intent should never come up in your code. If you have it in your code, kindly delete it now.
- Any comment that forces you to look somewhere else for its meaning has definitely lost touch with reality about what a comment should be and should, therefore be deleted.
- Writing redundant comments that explain what is already done. According to a quote, there is no more waste of time than doing something very well but not needed. So is a redundant comment.
- Mandating each function and variables to have comments. Some still do need it no matter how much we make our documentation look, but it should no longer be a compulsory item every function and variables should have.
- Journal comments to show who worked on a file the last time. These types of comments are important for easy referral when something goes wrong. However, using our source control tools pretty well can help avoid this. And I think that is a better way to handle such things than making more bunch of comments.
- Use a comment when you could have used a good function or variable name.
- Closing Brace comments to explain each closing brace. These are mostly used when your functions are really long. For short functions, these would be unnecessary.
- Commenting out your code and leaving it there. It is like eating and leaving your plate in the dining. Please do not leave commented code in your project as others are afraid of removing them. This leads to a lot of unwanted code
- Offering too much information. Know when to stop your comments. Some just become noise
These are few tips concerning really bad comments. Try as much as you can to avoid them in your project. It makes it easier for us all.
These tips are From the Book “Clean Code”