Comments

From Wikibooks, open books for an open world
Jump to: navigation, search

Unicode Java Programming
Comments
Coding conventions
Navigate Language Fundamentals topic: v  d  e )


A comment allows to insert text that will not be compiled nor interpreted. It lets you add some text to the source code. It can appear anywhere in the source code where whitespaces are allowed.

It is useful for explaining what the source code does:

  • explain the adopted technical choice: why this given algorithm and not another, why calling this given method...
  • explain what should be done in the next steps (the TODO list): improvement, issue to fix...
  • give the required explanation to understand the code and be able to update it yourself later or by other developers.

It can also be used in order that the compiler ignore a portion of code: temporary code for debugging, code under development... It is also useful for the class documentation.

Syntax[edit]

The comments in Java use the same syntax as in C++.

An end-of-line comment starts with two slashes and ends with the end of the line. This syntax can be used on a single line too.

Example Code section 3.105: Slash-slash comment.
  1. // A comment to give an example
    
  2.  
    
  3. int n = 10; // 10 articles
    

A comment on several lines is framed with '/' + '*' and '*' + '/'.

Example Code section 3.106: Slash-star comment in multiple lines.
  1. /*
    
  2.  * This is a comment
    
  3.  * on several lines.
    
  4.  */
    
  5.  
    
  6. /* This also works; slash-star comments may be on a single line. */
    
  7.  
    
  8. /*
    
  9. Disable debugging code:
    
  10.  
    
  11. int a = 10;
    
  12. while (a-- > 0) System.out.println("DEBUG: tab["+a+"]=" + tab[a]);
    
  13. */
    

By convention, subsequent lines of slash-star comments begin with a star aligned under the star in the open comment sequence, but this is not required. Never nest a slash-star comment in another slash-star comment. If you accidentally nest such comments, you will probably get a syntax error from the compiler soon after the first star-slash sequence.

Warning Code section 3.107: Nested slash-star comment.
  1. /* This comment appears to contain /* a nested comment. */
    
  2.  * The comment ends after the first star-slash and
    
  3.  * everything after the star-slash sequence is parsed
    
  4.  * as non-comment source.
    
  5.  */
    

If you need to have the sequence */ inside a comment you can use html numeric entities: */.

Slash-star comments may also be placed between any Java tokens, though not recommended:

Example Code section 3.108: Inline slash-star comment.
  1. int i = /* maximum integer */ Integer.MAX_VALUE;
    

However, comments are not parsed as comments when they occur in string literals.

Example Code section 3.109: String literal.
  1. String text = "/* This is not a comment. */";
    

It results in a 33 character string.

Test your knowledge

Question 3.26: Consider the following code:

Example Question 3.26: Commented code.
int a = 0;
// a = a + 1;
a = a + 1;
/*
a = a + 1;
*/
a = a + 1;
// /*
a = a + 1;
// */
a = a /*+ 1*/;
a = a + 1; // a = a + 1;
System.out.println("a=" + a);

What is printed in the standard output?

Answer
Standard input or output Output for Answer 3.26
a=4
Example Answer 3.26: Commented code.
  1. int a = 0;
    
  2. // a = a + 1;
    
  3. a = a + 1;
    
  4. /*
    
  5. a = a + 1;
    
  6. */
    
  7. a = a + 1;
    
  8. // /*
    
  9. a = a + 1;
    
  10. // */
    
  11. a = a /*+ 1*/;
    
  12. a = a + 1; // a = a + 1;
    
  13. System.out.println("a=" + a);
    

The highlighted lines are code lines but line 11 does nothing and only the first part of line 12 is code.

Comments and unicode[edit]

Be aware that Java still interprets Unicode sequences within comments. For example, the Unicode sequence \u002a\u002f (whose codepoints correspond to */) is processed early in the Java compiler's lexical scanning of the source file, even before comments are processed, so this is a valid star-slash comment in Java:

Example Code section 3.110: Unicode sequence interruption.
  1. /* This is a comment. \u002a\u002f
    
  2. String statement = "This is not a comment.";
    

and is lexically equivalent to

Example Code section 3.111: Unicode sequence interruption effect.
  1. /* This is a comment. */
    
  2. String statement = "This is not a comment.";
    

(The '*' character is Unicode 002A and the '/' character is Unicode 002F).

Similar caveats apply to newline characters in slash-slash comments.

For example:

Warning Code section 3.112: New line.
  1. // This is a single line comment \u000a This is code
    

That is because the \u000a is the Unicode for a new line, making the compiler think that you have added a new line when you haven't.

Javadoc comments[edit]

Javadoc comments are a special case of slash-star comments.

Example Code section 3.113: Javadoc comment.
  1. /**
    
  2.  * Comments which start with slash-star-star are Javadoc comments.
    
  3.  * These are used to extract documentation from the Java source.
    
  4.  * More on javadoc will be covered later.
    
  5.  */
    
Unicode Java Programming
Comments
Coding conventions