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

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?

Answer 2

If you come back to your code in two weeks and you can't easily figure out what you did, it either requires more comments, or refactoring to make the code clearer.

That said, guidelines for comments should come from your workplace's policies, or in your case, from your teacher. If your teacher is saying that you don't need comments in a certain place, then you don't.

When you're done with the class, feel free to comment any way you want.

Answer 3

Comments are for the reader of the code. Of course, the reader of the code may also be the writer. But either way, you want to tell the reader things they can't easily see from the code. Excessive or redundant comments just tend to get out of sync with the real code.

Answer 4

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 5

The big things I comment:

• The name of an algorithm. For example, if I'm writing an algorithm to compute the pixels in a line between two points I'd leave a comment saying it is an implementation of Bresenham's algorithm.

• If I am sending a hard coded, magic, value to a function (e.g. true, null, 42, etc.) I'd comment what that value represents.

• If I implement a data structure, I like to comment saying what operations it is designed to optimize. For example, if I was implementing a queue (admittedly, you'd use a framework for a queue) I'd say something like FIFO data structure with O(1) insert, remove, and size.

• I try to leave a comment at the top of every class and method whose name doesn't reveal all the intricacies of the implementation. However, I'm often hesitant to do this at all. More often than not, when faced with this problem a refactoring is more appropriate.

Answer 6

First off having readable code and readable comments are two things that are totally different. Readable code is code the uses good variable, method, class names, etc.

Readable comments are more a matter of personal taste. Some people like comments to follow grammatical rules that would be used to write a book while others couldn't care less about grammatical stuff.