Introduction to Comments

Comments are blocks of readable text inserted into code for the benefit of other programmers; both those who must use the code and those who must modify it. Comments are ignored by the compiler, so they need not adhere to any particular syntax.

Java recognizes traditional C-style comments. Traditional C-style comments are delimited by /* ... */ and can span more than one line. C compilers ignore all text after the opening /* up until a subsequent */, which means that comments cannot be nested. (Some C++ compilers detect nested C style comments and warn the user about them.)

Java also recognizes C++-style comments. In C++ comments are written starting with two slashes, like this: // ..., and run up to the end of that line of text. They cannot span more than one line: in a multi-line comment, each line must start with //. Comments like this are recommended because they can be nested inside C-style comments.

Java also extends the traditional C-style comment by starting with /**. This would be recognized as a conventional comment. In addition, a comment beginning with /** provides a documentation tool that can extract comments from source code to create external documentation. When a programmer embeds comments like this in code, that programmer is simultaneously writing its documentation.

Java has a special comment form which produces online documentation and is read by a javadoc, too.

/** This is a “doc” comment */