Over a million developers have joined DZone.

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

Commenting isn't universal. Learn more about commenting best practices, and go on a quest to find the perfect comment.

· Integration Zone

Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.

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

The Integration Zone is brought to you in partnership with CA Technologies.  Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.

comment,java,coding,coding conventions,code as craft

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}