Commenting Conventions

Question

I want to know what are some guidelines for commenting? I am coding in Java for class. I want to have readable code. In another question I was told "how" comments should be reserved for difficult sections of code. I was told that my code comments added no knew information. Comments are not only for readers. They are also reminders to the writer of their original intent and to help match grouping symbols.

I am new to Java and Stackoverflow. Why am I getting greifed? I thought this website was designed to allow programmers to help each other. I feel like a target because I have a question with a -3 vote. Are we here to help new programmers or here to puff up our chests with pride at others expense?

Answer 1

Different people have different styles, so to some extent whatever you read here will be just someone's suggestions. There are no cold, hard rules for commenting.

The most important thing you should know about commenting in Java is Javadocing. It's a special type of comment that can be parsed out and used in IDEs (like Eclipse and Netbeans), to help make the coding process easier. Javadoc comments start with a /** and end with a */ It's just like a regular multi-line comment but with two asterisks in the first one.

You put Javadoc comments at the beginning of classes, methods, or instance variables to describe what they do. There are standard ways to format data in the comment, which are tags. Some common tags are @author and @version. You can see some of Sun's suggestions for writing Javadoc comments here: http://java.sun.com/j2se/javadoc/writingdoccomments/

What I like to do after that is use single-line comments ( the double slash // ) to describe my logic. If I need more than one line, I'll just use multiple single-line comments. The advantage of this technique is that if you need to later comment out large swaths of text, you can use the regular multi-line comment /* */ without worrying about the nested comment problem.

I hope that helps you get a rough idea of how to use comments in java. My advice is partly a product of the teaching assistant job I have for a university's Intro Java class and partly from working in industry. Others with different background may have more suggestions.

Answer 2

I'd follow the Stack Overflow guidelines mentioned in the following posts:

• When Not to Comment Code
• Function/Class Comment formatting Conventions
• What is your personal approach / take on Commenting?