- Java comments are notes in a Java code file that are ignored by the compiler and runtime engine. They are used to annotate the code in order to clarify its design and purpose. You can add an unlimited number of comments to a Java file,but there are some "best practices" to follow when using comments
- Generally, code comments are "implementation" comments that explain the source code, such as descriptions of classes, interfaces, methods, and fields.
- Another type of Java comment is a Javadoc comment. Javadoc comments differ slightly in syntax from implementation comments and are used by the program javadoc.exe to generate Java HTML documentation.
Why Use Java Comments ?
- Putting Java comments into your source code to enhance its readability and clarity for yourself and other programmers. It isn't always instantly clear what a section of Java code is performing. A few explanatory lines can drastically reduce the amount of time it takes to understand the code.
- Implementation comments in Java code are only there for humans to read. Java compilers don't care about them and when compiling the program, they just skip over them.
- The size and efficiency of your compiled program will not be affected by the number of comments in your source code.
- Implementation Comments
- Implementation comments come in two different formats:Line Comments: For a one line comment, type "//" and follow the two forward slashes with your comment. For example:
- When the compiler comes across the two forward slashes, it knows that everything to the right of them is to be considered as a comment.
- This is useful when debugging a piece of code. Just add a comment from a line of code you are debugging, and the compiler.
- You can also use the two forward slashes to make an end of line comment:
- To start a block comment, type "/*". Everything between the forward slash and asterisk, even if it's on a different line, is treated as a comment until the characters "*/" end the comment. For example:
- Use special Javadoc comments to document your Java API. Javadoc is a tool included with the JDK that generates HTML documentation from comments in source code.
- A Javadoc comment in .java source files is enclosed in start and end syntax like so: /** and */. Each comment within these is prefaced with a *.
- Place these comments directly above the method, class, constructor or any other Java element that you want to document. For example:
- Javadoc incorporates various tags that control how the documentation is generated. For example, the @param tag defines parameters to a method:
Tips for Using Comments
- Don't over comment.Every line of your program does not need to be explained. If your program flows logically and nothing unexpected occurs, don't feel the need to add a comment.
- Indent your comments. If the line of code you are commenting is indented, make sure your comment matches the indentation.
- Keep comments relevant. Some programmers are excellent at modifying code, but for some reason forget to update the comments. If a comment no longer applies, then either modify or remove it.
- Don't nest block comments. The following will result in a compiler error: