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 */

3 Faulty Constructions of In-Line Lists

3 Faulty Constructions of In-Line Lists 3 Faulty Constructions of In-Line Lists 3 Faulty Constructions of In-Line Lists By Mark Nichol The interrelationship of words or phrases in a list of things set out in a sentence (known as an in-line list, as opposed to a vertical list) is often obscured by erroneous syntax. For each of the following examples, discussion and revision point out the errors of equivalency. 1. The average large project runs 45 percent over budget, 7 percent past deadline, and delivers 56 percent less value than expected. The verb runs pertains to the first two figures but not to the last, so the first two list items must be connected by a conjunction to share it, and because doing so reduces the number of list items from three to two, no commas are necessary: â€Å"The average large project runs 45 percent over budget and 7 percent past deadline and delivers 56 percent less value than expected.† 2. Cybersecurity is a critical organizational priority in the boardroom, C-suite, information technology department, and every area of the business. Each of the first three items in this list, to be parallel with the final item, should have their own iteration of the: â€Å"Cybersecurity is a critical organizational priority in the boardroom, the C-suite, the information technology department, and every area of the business.† Alternately, the structure of the sentence can be altered so that the first three items constitute one larger item, which requires a couple of revisions to the sentence so that it and the final item are equivalent: â€Å"Cybersecurity is a critical organizational priority in the boardroom, C-suite, and information technology department and in every area of the business.† 3. Over the years, Jones would also master piano, bass guitar, clarinet, alto and tenor saxophone. Alto is not a distinct list item- it is part of the item â€Å"alto and tenor saxophone†- so that phrase must be preceded by a conjunction: â€Å"Over the years, Jones would also master piano, bass guitar, clarinet, and alto and tenor saxophone.† Want to improve your English in five minutes a day? Get a subscription and start receiving our writing tips and exercises daily! Keep learning! Browse the Style category, check our popular posts, or choose a related post below:50 Idioms About Talking25 Russian Words Used in English (and 25 More That Should Be)6 Foreign Expressions You Should Know