The Perfect Comment (and Why I Haven't Found It)

Best Practices in Commenting

JavaDoc (or if another language, find your equivalent), for Go it’s Go Doc, the start of your class with necessary information. You can setup templates in the editor of your choosing so it can put in all the boilerplate code about license, names, author, and the basics. I really like to see a short reason why this exists. Is it still used? A pointer to a JIRA ticket or some other article is very important. A link or reference to the code used to test this class.

If you have a complex method there should be a comment, if it’s so complex your comment is huge, then there’s probably something wrong with the code. Break down the problem, test and retest and simplify. Remember most time is spent reading code and doing maintenance, make it easier on yourself and others. Send the good vibes on by writing concise, simple code that is well tested and has some basic comments. Don’t comment every line, don’t use filler comments. Add comments that mention a special algorithm, stakeholder, use case, JIRA ticket or some other kernel of knowledge. Sometimes I’ll add a link to an online resource that important, say if it’s for something like a third party library.I like a comment that gives you an idea how to run it or test it, especially if it’s a little weird.  Even if it’s just see: JMeter Project “Main Page/Mail Us.”

The Quest for the Perfect Comment

I am hoping some people will comment and tell me what their all-time favorite comment is. I have seen some funny ones and when I was in 4th grade I like to add ASCII pictures to my comments for Apple II Basic code. I am talking the perfect comment. You see it, you know exactly what you need to work with, change or use the program it comments. I have seen some good ones mentioning documentation or pointing you what you need to do.   

I don’t think I have found the perfect comment. The elusive purple squirrel of comments that makes all others pale in comparison. Maybe that’s silly. It would be nice just to see consistent useful comments. Unless the code is so simple and includes full code coverage with elegantly readable tests, where I have all I need in the tests. I would prefer the documentation be the tests. If the tests all run, then I know I have met the needs of the Product Owner. The only comment needed is a JIRA ticket or a link to a system mentioning the project, stakeholders and contact information.

Helpful Links on Commenting

Commenting Best Practices

How to Write Readable Code

Google Java Guide Comment Recommendations

Microsoft Comment Guideline

Source Code Comment Styling Tips

Best Coding Practices (Commenting)

What a University was expecting from their student’s comments