// Commenting Code

Comments segments of text placed inside of source code that are not compiled. They serve simply to help the programmer and user to understand what the code is doing and why. There are many different types of comments, as well. Among others, there can be title comments, documentation comments, even legal comments. For example, many commercial Open Source projects must add in the GNU Public License, in the form of a large block comment, to the top of every file in their code.

/*
* This is a block comment.
* It is not compiled. It is only used for    
* notation purposes.
*/

Comments must be led by a specific language-defined character or characters that tells the compiler, "This is a comment, please ignore." As an example, Java uses double slashes (//), and Shell Scripts use pound symbols (#). In the picture is my testing script that I wrote two weeks ago. All the gray text is commented code. Obviously, I went a little overboard on the comments, as most of what was said in them can be easily inferred from the actual code. This style of commenting is typically frowned upon in larger programming projects, because some say that it clutters the code even more. A popular saying among programmers is, "Don't comment code, comment decisions." This limits comments to only the most important statements.

Interestingly enough, the Java JDK includes a tool, called Javadoc, that allows programmers to make code documentations from their comments, using keywords like "@params ... " and "@returns ... ." Using Javadoc may be one of the only times where it is necessary for the programmer to heavily comment every public method in all their classes.

In conclusion, comments are a good way for a programmer to write down what his intentions are for the code, and note any important or confusing code. As long as they are not overdone, comments can be incredibly helpful.

// Thanks for reading, as always!
// -Jeff