Comentários #

Os programas em Java podem ter dois tipos de comentários: de implementação e de documentação. Comentários de implementação são aqueles encontrados em C++, os quais são delimitados por / . . . /, e / /. Comentários de documentação (conhecidos como “doc comments” ou “Javadoc”) são específicos do Java, sendo delimitados por / . . . /. Comentários Javadoc podem ser extraídos para arquivos HTML usando-se a ferramenta javadoc.

Comentários de implementação são feitos para se descrever com detalhes um código em particular. Já os comentários Javadoc servem para descrever a especificação de um código a partir de uma perspectiva livre de implementação a ser lida por desenvolvedores que não necessariamente tenham o código fonte em mãos.

Comentários devem ser usados para dar uma visão geral do código e fornecer informação adicional que não esteja prontamente disponível no próprio código. Comentários devem conter somente informações relevantes para a leitura e entendimento do programa. Por exemplo, informações sobre como determinado pacote é construído ou em qual diretório ele reside não devem ser incluídas como um comentário.

Discussões sobre decisões não triviais ou não óbvias são apropriadas, porém evite duplicar informações que já estejam presentes e de maneira clara no código. É muito fácil os comentários redundantes ficarem desatualizados. Em geral, evite quaisquer comentários prováveis de ficarem obsoletos ou desatualizados à medida que o código evolui.

A frequência dos comentários por vezes reflete baixa qualidade do código. Quando você se sente forçado a incluir um comentário, considere reescrever o código para deixá-lo mais limpo.

Comentários não devem ser colocados em grandes caixas de desenho com asteriscos ou outros caracteres. Comentários nunca devem incluir caracteres especiais tais como form-feed e backspace.

Formatos para implementação de comentários #

Os programas podem ter quatro estilos de implementação de comentários: bloco, linha única, trailing e final de linha.

Comentário de bloco #

Comentários de bloco são usados para fornecer descrições de arquivos, métodos, estruturas de dados e algoritmos. Comentários de bloco podem ser usados no início de cada arquivo e antes de cada método. Eles podem também ser usados em outros lugares, tais como dentro dos métodos. Comentários de bloco dentro de uma função ou método devem ser indentados no mesmo nível do código o qual descrevem.

Um comentário de bloco deve ser precedido por uma linha em branco para separá-lo do resto do código. Comentários de bloco possuem um asterisco “” no início de cada linha exceto a primeira.

/* 
 * Eis um comentário de bloco. 
 */ 

Comentário de linha única #

Comentários curtos podem aparecer em uma linha simples indentada no nível do código que se segue. Se um comentário não puder ser escrito em uma única linha, este deverá seguir o formato de comentário de bloco (ver item anterior). Um comentário de linha única deverá ser precedido de uma linha em branco. Eis um exemplo de um comentário de linha única em um código Java.

if (condição) { 
    /* Comentário para o tratamento da condição. */ 
    ... 
} 

Comentário do tipo trailing #

Comentários muito curtos podem aparecer na mesma linha de código, mas deverão estar longe o suficiente para separá-los de outras instruções. Se mais de um comentário curto aparecer em um bloco de código, todos eles deverão usar a mesma indentação ou tabulação.

Eis um exemplo de comentário do tipo trailing em um código Java:

if (a == 2) { 
    return TRUE;           /* caso especial */ 
} else { 
    return numeroPrimo(a); /* funciona apenas para os ímpares */ 
} 

Comentário de final de linha #

O delimitador de comentário “” pode ser utilizado para comentar toda uma linha de código ou apenas parte dela, e não deve ser usado em múltiplas linhas consecutivas para comentários de texto. Entretanto, ele pode ser usado em múltiplas linhas consecutivas para comentar seções de código. A seguir exemplos dos três estilos citados://

if (foo > 1) { 
     // realizar um flip duplo
     ... 
} 
else 
     return false;          // Explicar a funcionalidade aqui.

Não é recomendado comentar códigos não utilizados, pois o controle de versões possue esta informação

//if (bar > 1) { 
// 
//     // realizar um flip triplo
//     ... 
//} 
//else 
//     return false;

Comentários de documentação #

Comentários de documentação (ou do tipo doc) descrevem classes Java, interfaces, construtores, métodos e campos. Cada comentário doc é definido dentre os delimitadores /.../ tendo um comentário por classe ou interface. Este comentário deverá aparecer logo antes das declarações da seguinte forma:

/** 
 * Descrição geral da classe. 
 * 
 * @javadoc
 */ 
public class Exemplo { ... 

A primeira linha de um comentário de documentação (/) não é indentada, e as linhas subsequentes têm cada uma o seu espaço de indentação verticalmente, de forma que os asteriscos fiquem alinhados.

Comentários de documentação não devem ser colocados dentro de um bloco de definição de método ou construtor, pois o Java os associa com a primeira declaração logo após o comentário.

Sendo assim, um comentário de documentação divide-se em duas seções: descrição geral sobre a funcionalidade exercida pelo código em questão e informações especiais para a confecção da documentação pela ferramenta Javadoc.

A descrição geral indica a abrangência da classe, interface ou método, indicando funcionalidades e esclarecendo as regras de negócio envolvidas na documentação.

Por outro lado, as informações especiais possuem um formato pré-estabelecido. Considere consultar o documento How to Write Doc Comments for Javadoc para obter maiores detalhes sobre o assunto. De maneira resumida, as marcações no Javadoc são definidas através de um @nome_tag, cujo propósito é de melhor estruturar a documentação final gerada.

Tags do Javadoc #

Eis algumas tags pré-definidas para a utilização via Javadoc:

Utilização de código HTML nos comentários #

Você pode opcionalmente incluir tags HTML na descrição do comentário Javadoc a fim de possibilitar uma leitura mais facilitada da documentação, uma vez que essa será traduzida para o formato HTML. Por exemplo:

/**
 * Você pode <b>também</b> incluir uma <i>lista</i>:
 * <ol>
 *   <li>elemento 1</li>
 *   <li>elemento 2</li>
 *   <li>elemento 3</li>
 * </ol>
 * e hiperlinks : {@link classe#metodo}
 */ 

As seguintes tags HTML estão disponíveis no Javadoc:

• <p>...</p>: definição de um parágrafo de texto;
• <b>...</b>: texto em negrito;
• <i>...</i>: texto em itálico;
• <u>...</u>: texto sublinhado;
• <a>...</a>: inclusão de links de hipertexto para documentos externos (arquivos técnicos, descrição de algoritmos, etc);
• <ol><li>...</li>...</ol>: organiza texto em listas de marcadores;
• <br>: quebra de linha no texto.

Utilização de comentários no Demoiselle #

Nos códigos fontes do Framework Demoiselle não serão utilizadas as seguintes tags: @author, @since e @version. Tal diretiva visa garantir com que a documentação Javadoc esteja sempre atualizada com os códigos fontes. Além disso, as informações detalhadas sobre versionamento, datas e autoria serão melhores gerenciadas pelo repositório (atualmente Subversion).

Não devem ser criados comentários de documentação do tipo Javadoc nas seguintes situações:

• métodos oriundos de interfaces implementadas pela classe – tais métodos precisam ser documentados no código da interface;
• métodos sendo sobrescritos através de herança – tais métodos precisam estar devidamente documentados na superclasse;
• atributos de classe ou de instância – não haverá geração de documentação estruturada para estes, e para isso pode-se utilizar comentário convencional.

Exemplos de utilização em declarações #

Documenta a funcionalidade da classe, interface, enumeração ou anotação explicando seu objetivo e as funcionalidades abrangentes aos seus métodos e atributos.

Classe #

/**
* Authenticator that actually does nothing but raise exceptions.
*
* @author SERPRO
* @see Authenticator
*/
public class DefaultAuthenticator implements Authenticator {

Interface #

/**
Structure used to handle pagination of data results on both <i>backend</i> (i.e., persistence) and <i>frontend</i>
(i.e., presentation) layers in the application.
@author SERPRO
**/
public interface Pagination {

Enumeração #

/**
 * Defines available mailing mechanisms: a local resource or provided by the
 * application server.
 */
public enum MailType {

Anotação #

/**
* Identifies a method eligible to be executed automatically during **application initialization**.
*

*public class Initializer {
*
* @Startup(priority = 1)
* public void initialize() {
* ...
* }
*}

* <p>
* The @Startup annotation allows an integer value to be defined, which stands for the method execution
* priority when several initializer classes are available in the application.
*
* @author SERPRO
*/
@Target(METHOD)
@Retention(RUNTIME)
public @interface Startup {

Exemplos de utilização em atributos e métodos #

Documenta uma funcionalidade específica concernente ao campo ou método em questão. Para uma documentação de qualidade é importante observar que a primeira sentença do método deve conter uma descrição breve e objetiva terminando em ponto final.

/**
* Delegates the injection function to its specific factory.
* 
* @param object	the object to search for injections
*/
public void execute(Object object) {

Métodos que estão obsoletos e serão eliminados nas próximas versões da API devem obrigatoriamente ser assinalados com a diretiva @deprecated, tal como no modelo a seguir:

/** 
 * @deprecated 
 * @see #metodoNovo 
 */ 
@Deprecated
public void metodoAnterior() {