Comments inside classes

You use comments in your classes and interfaces to document them to help developers understand the contents of your class. You might start all your class files with a comment that provides the class name, its version number, the date, and your copyright. For example, you might create documentation for your class that is similar to the following comment:

/**
  Pelican class
  version 1.2
  10/10/2005
  copyright Adobe Systems Incorporated
*/

Use block comments to describe files, data structures, methods, and descriptions of files. They are usually placed at the beginning of a file and before or within a method.

There are two kinds of comments in a typical class or interface file: documentation comments and implementation comments. Documentation comments are used to describe the code's specifications and do not describe the implementation. You use documentation comments to describe interfaces, classes, methods, and constructors. Implementation comments are used to comment out code or to comment on the implementation of particular sections of code.

Include one documentation comment per class, interface, or member, and place it directly before the declaration. If you have additional information to document that does not fit into the documentation comments, use implementation comments (in the format of block comments or single-line comments). Implementation comments directly follow the declaration.

The two kinds of comments use slightly different delimiters. Documentation comments are delimited with /** and */, and implementation comments are delimited with /* and */.

TIP

Don't include comments that do not directly relate to the class being read. For example, do not include comments that describe the corresponding package.

You can also use single-line comments, block comments, and trailing comments in class files. For more information on these kinds of comments, see the following sections:

View comments on LiveDocs