How to Use Comments in Java Code

How to Use Comments in Java Code 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. These are usually a couple of lines written above or beside Java code to clarify what it does. 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? Its good practice to get into the habit of putting Java comments into your source code to enhance its readability and clarity for yourself and other programmers. It isnt 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. Do They Affect How the Program Runs? Implementation comments in Java code are only there for humans to read. Java compilers dont 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: // this is a single line comment int guessNumber (int) (Math.random() * 10); 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 wont see it: // this is a single line comment // int guessNumber (int) (Math.random() * 10); You can also use the two forward slashes to make an end of line comment: // this is a single line comment int guessNumber (int) (Math.random() * 10); // An end of line comment Block Comments: To start a block comment, type /*. Everything between the forward slash and asterisk, even if its on a different line, is treated as a  comment until the characters */ end the comment. For example: /* this is a block comment */ /* so is this */ Javadoc Comments 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: // myClass.java/** * Make this a summary sentence describing your class.* Heres another line. */public class ​myClass{...} Javadoc incorporates various tags that control how the documentation is generated. For example, the  param  tag defines parameters to a method: /** main method * param args String[] */​ public static void main(String[] args) ​{ ​ System.out.println(Hello World!);​ } Many other tags are available in Javadoc, and it also supports HTML tags to help control the output. See your Java documentation for more detail. Tips for Using Comments Dont over comment. Every line of your program does not need to be explained. If your program flows logically and nothing unexpected occurs, dont 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.Dont nest block comments. The following will result in a compiler error: /* this is /* This block comment finishes the first comment */ a block comment */