Java Comment Dilemma

Question

This was a question on my assignment:

Which of the following is not an acceptable way of indicating comments? Why?

• /** comment */
• /* comment */
• // comment
• // comment comment
• /*comment comment */

In all honestly, they all look fine to me. But I was thinking that it could be /** comment */ because it's not multi-lined in the example but that's its purpose--documentation. What do you think? This is the only question that's giving me a hard time. Any help would be appreciated! Thank you.

Answer 1

In terms of grammar, none of the above ways of indicating comments is not acceptable. However, to make other people easier to understand your code, then I would suggest to follow some of the major coding styles.

For example, the Oracle coding style is one of the popular coding styles for Java.

In its coding style, there are two types of comments. The first is implementation comment, which uses /* */ for block comments and // for single line comments.

    /*
     * Here is a block comment.
     */


    // Here is a single line comment.

The second type is the documentation comment, which usually uses /** */ styled comment and only appears right before the class, function, and variable definitions. For example:

    /**
     * Documentation for some class.
     */
    public class someClass {

      /**
       * Documentation for the constructor.
       * @param someParam blah blah blah
       */
      public someClass(int someParam) {
        ...
      }
      ...
    }