Gosu commenting best practices

As a commenting best practice, always place block comments before every class and method that you write. Briefly describe the class or method in the block comment. For comments that you place within methods, use any of the commenting styles to help clarify the logic of your code.

Block comments provide descriptions of libraries and functions. A block comment begins with a slash followed by an asterisk (/*). A block comment ends with an asterisk followed by a slash (*/). To improve readability, place an asterisk (*) at the beginnings of new lines within a block comment.

/*
 * This is a block comment.
 * Use block comments at the beginnings of files and before
 * classes and functions.
 */

Place block comments at the beginnings of files, classes, and functions. Optionally, place block comments within methods. Indent block comments within functions to the same level as the code that they describe.

Javadoc comments provide descriptions of classes and methods. A Javadoc comment begins with a slash followed by two asterisks (/**). A Javadoc comment ends with a single asterisk followed by a slash (*/).

/**
 * Describe method here--what it does and who calls it.
 * How to Call: provide an example of how to call this method
 * @param parameter description (for methods only)
 * @return return description (for methods only)
 * @see reference to any other methods, 
 * the convention is 
 * <class-name>#<method-name>
 */

Block comments that you format using Javadoc conventions allow automated Javadoc generation.

Single-line comments provide descriptions of one or more statements within a function or method. A single-line comment begins with double slashes (//) as the first two characters two non-whitepsace characters on a line.

//  Handle the condition 
if (condition) {
  ...
}

If you cannot fit your comment on a single line, use a block comment, instead.

Trailing comments provide very brief descriptions about specific lines of code. A trailing comment begins with double slashes (//) following the code that the comment describes. Separate the double slashes from the code with at least two spaces.

if (a == 2) {
  return true  // Desired value of ’a’ 
}
else {
  return false // Unwanted value of ’a’ 
}

If you place two or more trailing comments on lines in a block of code, indent them all to a common alignment.

Use a single-line comment delimiter (//) to comment out a complete or partial line of code. Use a pair of block comment delimiters (/*, */) to comment out a block of code, even if the block you want to comment out contains block comments.

Use caution if you include slashes and asterisks within block comments to set off or divide parts of the comment. For example, do not use a slash followed by a line of asterisks as a dividing line within a block comment. In the following example, the compiler interprets the dividing line as the beginning of a nested comment (/*) but finds no corresponding closing block comment delimiter (*/).

/*
    The dividing line starts a nested block comment and causes an unclosed comment compiler error. 
    //********************************************************************************************
*/

In the preceding example, compilation fails due to an unclosed comment. The following example avoids compilation errors by inserting a space between the slash and the first asterisk.

/*
    The dividing line does not start a nested block comment and causes no compiler error.
    // **********************************************************************************
*/

Single-line comment delimiters (//) are ignored in block comments.