2.1.4 Comentários

2.1.4.1 Comentários de Implementação

Os comentários de implementação devem ser usados para dar detalhes sobre uma dada linha ou bloco de instruções que permitam uma facilidade maior sobre o entendimento daquela parte específica da implementação. É importante observar comentários de implementação não devem explicar o que está ocorrendo naquele trecho de código, pois isso já deve ser feito pela prática do código autoexplicativo. Comentários de implementação servem para dar detalhamentos cujo único meio de passá-los é por palavras, como a unidade de medida de um determinado dado, ou a razão para a implementação ser de um jeito e não de outro.

Todos os comentários devem iniciar com letra maiúscula e terminar com um ponto final.

2.1.4.1.1 Comentários em Blocos

Os comentários em bloco são usados quando não é possível dizer o necessário numa única linha. São utilizados para fornecer as descrições de estruturas de dados e algoritmos. Comentários em bloco podem ser utilizados dentro de métodos. Os comentários em bloco dentro de um método devem ser recuados para o mesmo nível que o código que eles descrevem.

Segue um exemplo de comentário em bloco.

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

2.1.4.1.2 Comentários de Linha

Comentários curtos podem aparecer em uma única linha recuado para o nível do código que se segue. Se um comentário não pode ser escrito em uma única linha, deve seguir o formato bloco de comentário.

Um exemplo de comentário de uma linha só segue abaixo:

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

2.1.4.1.3 Comentários de Fim de Linha

O // delimitador de comentário pode comentar uma linha completa ou apenas uma linha parcial. Não deve ser usado em várias linhas consecutivas para comentários em texto.

Deve ser usado para pequenos comentários sobre detalhes em uma linha, como comentar unidades de medida de uma determinada variável. Segue um exemplo.

private double area = 0; // Square meters.

2.1.4.2 Comentários de Documentação

Comentários de documentação descrevem classes Java, interfaces, construtores, métodos e campos. Cada comentário de documentação deve ser colocado dentro de delimitadores de comentário /** ... */, com um comentário por classe, interface ou membro. Este comentário deve aparecer pouco antes da declaração. Um exemplo de como deve ser escrito:

/**
 * Exemplies how a 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.
 */

Notas:

• A primeira parte serve para descrever a classe, a interface ou o método.
• No marcador @param deve-se por o nome do parâmetro e, em seguida a um espaço em branco, uma pequena descrição daquele parâmetro.
• No marcador @return deve-se por uma pequena descrição do que é o retorno daquele método.
• Uma dica para gerar o javadoc é, após escrever o marcador /** , pressione a tecla ENTER. O Eclipse irá gerar os parâmetros e o retorno automaticamente. Fica faltando apenas as descrições.

2.1.4.3 Comentários Comuns (Marcações)

Alguns comentários são bastante comuns durante a codificação e, portanto, serão tratados como marcações.

A tabela a seguir traz os comentários comuns.

Marcação	Descrição
Nothing To Do	Deve ser usado quando o escopo de uma instrução não possui efeito algum. Normalmente usado quando uma instrução default, como o elseou o próprio default de um switchnão possui efeitos.
Write Instructions Here	Usado para avisar sobre a necessidade de uma implementação numa dada parte do código.
Empty Constructor	Usado para alertar que o construtor é vazio e deve permanecer vazio.
Empty Method	Usado para alertar que o método é vazio e deve permanecer vazio.

Esse tipo de comentário deve ser escrito da forma que é demonstrada no exemplo:

/* Empty Constructor. */