Comments

One of the nice things about compiled programming languages is that you are able to have as many comments as you wish and when the program is compiled all the comments will be automatically removed from the resulting file (in Java's case, the class file). Those of you new to programming may not understand what a comment is. Essentially, a comment is a line or block of lines that contain comment text. The comment text is whatever the programmer wants to put there, but is usually a description of what is happening with the program.

Comments are used by programmers to explain what the code does. This is because it is far faster to read a description of what a block of code does then it is to go line by line and figure out what the code does. Some readers are probably thinking that if you are writing the code you should have an idea of what the code is doing so comments aren't really useful. If you or somebody else never have to go back and alter or re-use the code you wrote then you would be correct. Maintenance and code re-use are very common tasks, so it is advisable to write comments.

Java supports three types of comments. Single line comments, Multi-line comments, and Javadoc comments. Javadoc comments will be explained in the next section.

Single line comments are designated by double slashes (//). These comments extend from the double slash to the end of the line. The double slash can start anywhere on a line and can even be on a line that has other programming statements on it. Just remember that anything after the comment is not going to be seen by the compiler. These type of comments are very convenient and are generally used within the middle of a block of code to explain complex code. Some programmers will use these comments before they write any code to break down a method into a series of simple tasks and will then fill in the rest of the method at a later time.

Multiple line comments start with the slash and asterisk symbols "/*" and continue until the asterisk and slash symbols "*/" are reached. Anything within this block is considered to be a comment. These comments can span a small portion of a line or can span multiple lines. This type of comment is generally used at the beginning of a method to describe what the method does, though javadoc comments have largely replaced this use. Another use for these comments is to block out large sections of code. This is useful to do if you are maintaining a program and don't want to lose the original code.

Java does not support nestling multi-line comments, meaning that "/* /* */ */" might not compile. It is possible, however, to have line comments contained within blocks. In other words, if you are planning on blocking out a section of code by using a multi-line comment, make sure there is not any multi-line comments within the area that you are blocking out.

There are many programmers who do not use comments. The primary reason for not using comments is the amount of time it takes to write comments. If the class is going to be used by other people there really is no reason to not write comments. With Java's javadoc comments (C++ does not support Javadoc format comments, though it would certainly be valid to use the same formatting, as the extra asterisk would be ignored. Writing a utility to create the document would be a bit of work, but certainly possible) there really is no excuse for at least commenting methods. While not all methods need a description, it is not a bad habit to get into. Things that should especially be noted within comment blocks is any type of restrictions or requirements that a method or method parameters require. To-do and assumptions can also be placed in this comment block.

One interesting argument that I heard for not commenting is that comments can become outdated and therefore be incorrect. What I don't understand, and have yet had explained to me, is how a competent programmer could see a comment that his or her changes is making invalid without him or her altering the comment or making note of the changes.