Comments

Navigate Language Fundamentals topic: Statements Conditional blocks Loop blocks Boolean expressions Variables Primitive Types Arithmetic expressions Literals Methods String Objects Packages Arrays Mathematical functions Large numbers Random numbers Unicode Comments Keywords Coding conventions Lambda expressions

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

It is useful for explaining what the source code does by:

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

It can also be used to make the compiler ignore a portion of code: temporary code for debugging, code under development...

Syntax

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.

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

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

Code section 3.106: Slash-star comment in multiple lines. /* * This is a comment * on several lines. */ /* This also works; slash-star comments may be on a single line. */ /* Disable debugging code: int a = 10; while (a-- > 0) System.out.println("DEBUG: tab["+a+"]=" + tab[a]); */

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.

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

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:

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

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

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

It results in a 33 character string.

Test your knowledge

Question 3.26: Consider the following code:

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

Output for Answer 3.26 a=4

Answer 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);

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

Comments and unicode

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:

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

and is lexically equivalent to

Code section 3.111: Unicode sequence interruption effect. /* This is a comment. */ 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:

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

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

Javadoc comments

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

Code section 3.113: Javadoc comment. /** * Comments which start with slash-star-star are Javadoc comments. * These are used to extract documentation from the Java source. * More on javadoc will be covered later. */