1.1.4 Comments

1.1.4.1 Comments Implementation

Implementation comments should be used to give details about a given row or block of statements enabling greater ease of understanding of that particular part of the implementation. It is important to note implementation comments are not explain what is happening in that code snippet, as this should already be done by the practice of self-explanatory code. Implementation comments are meant to give detailing whose only means of passing them is in words, as the unit of measurement of an item of data, or the reason for the implementation to be one way and not another.

All comments must start with a capital letter and end with a period.

1.1.4.1.1 Comments on Blocks

Block comments are used when you can not say needed a single line. They are used to provide descriptions of data structures and algorithms. Block comments may be used within methods. Block comments within a method should be indented to the same level as the code that they describe.

An example of block comment.

/*
 * This is a block comment. Note que comment block in there is blank space between the next text
 * And the marks que define the margin of comment and text.
 */

1.1.4.1.2 Comments Line

Short comments can appear on a single line indented to the level of the following code. If a comment can not be written in a single line, you should follow the block comment format.

An example of a single line comment only follows:

public void someMethod (firstParameter int, int secondParameter,
        thirdParameter int, String fourthParameter) {
    /* Write instructions Here. */
}

1.1.4.1.3 Comments of End of Line

The // comment delimiter can comment out a complete line or only a partial line. Not to be used in several consecutive lines for text comments.

It should be used for brief comments on details in a row, as commenting measurement units of a particular variable. Here's an example.

private double area = 0; // Square meters.

1.1.4.2 Comments Documentation

Doc comments describe Java classes, interfaces, constructors, methods and fields. Each documentation comment should be placed inside comment delimiters '/ ** ... * /', with one comment per class, interface, or member. This comment should appear just before the declaration. An example of how it should be written:

/**
  * Exemplies how the method with many parameters must be indented.
  *
  * @param FirstParameter first parcel in expression.
  * @param SecondParameter second parcel in expression.
  * @param ThirdParameter third parcel in expression.
  * @param FourthParameter fourth parcel in expression.
  *
  * @return Sum of the four parcel.
  */

Notes:

• The first part serves to describe the class, interface or method.
• In marker @param should be by the parameter name and then a blank, a short description of that parameter.
• In marker @return should be for a small description of what is the return that method.
• A tip to generate javadoc is, after writing the marker '/**', press the ENTER key. The Eclipse will generate the parameters and return automatically. It is just missing descriptions.

2.1.4.3 Comments Commons (Markings)

Some comments are quite common during encoding and therefore will be treated as markup.

The following table lists the common comments.

Marking	Description
Nothing To Do	Should be used when the scope of an instruction does not have any effect. Typically used when a statement default, such as else or the default himself of a switch hasn't effects.
Write Instructions Here	Used to warn of the need for an implementation in a given piece of code.
Empty Constructor	Used to alert the constructor is empty and must remain empty.
Empty method	Used to warn that the method is empty and must remain empty.

This type of comment should be written the way it is demonstrated in the sample:

/* Empty Constructor. */