Convenção desenvolvedor/Convenção código/Comentários

Convenção desenvolvedor/Convenção código/Comentários 1.1 (Edição mínima)

2013-01-09T20:00:14Z

Linha 1

<<TableOfContents>>

Linha 2

Linha 3

== Comentários ==

Linha 4

Linha 5

=== Formatos para implementação de comentários ===

Linha 6

Linha 7

==== Comentário de bloco ====

Linha 8

Linha 9

==== Comentário de linha única ====

Linha 10

Linha 11

==== Comentário do tipo trailing ====

Linha 12

Linha 13

==== Comentário de final de linha ====

Linha 14

Linha 15

=== Comentários de documentação ===

Linha 16

Linha 17

==== Tags do Javadoc ====

Linha 18

Linha 19

==== Utilização de comentários no Demoiselle ====

Linha 1

~~New~~

Convenção desenvolvedor/Convenção código/Comentários 1.2 (Edição mínima)

2013-01-09T20:00:14Z

Linha 20

==== Utilização de comentários no Demoiselle ====

Convenção desenvolvedor/Convenção código/Comentários 1.3 (Edição mínima)

2013-01-09T20:00:14Z

Linha 5

== 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 [5] podem ser extraídos para arquivos HTML usando-se a ferramenta javadoc [6].

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.

Linha 27

==== Utilização de comentários no Demoiselle ====

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

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

Convenção desenvolvedor/Convenção código/Comentários 1.4 (Edição mínima)

2013-01-09T20:00:14Z

Linha 6

Linha 7

Linha 8

Linha 9

Dis~~cussõ~~es s~~obr~~e d~~eci~~s~~ões~~ ~~não t~~r~~ivi~~ais ou ~~não ób~~vias são apr~~opri~~ad~~as,~~ po~~rém~~ e~~vite~~ ~~dupli~~car informaç~~ões~~ que já estejam presentes e d~~e ma~~ne~~ira c~~l~~ara~~ no código. É muit~~o f~~ácil os comentários re~~dund~~antes ~~fic~~arem ~~des~~atualizados. Em geral, evite ~~quai~~s~~que~~r comentários pro~~váv~~eis de fic~~arem~~ obs~~ole~~tos ou de~~sat~~ual~~iza~~dos à medid~~a qu~~e o cód~~igo~~ evolui.

Linha 9

Linha 10

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.

Linha 10

Linha 11

Comentários não devem ser co~~loc~~ados em ~~grand~~es caixas de dese~~nho co~~m asteris~~cos~~ ou ~~out~~ros caract~~ere~~s. Comentários nunca devem ~~inc~~luir c~~aract~~eres especiais tais ~~como~~ ~~for~~m-feed e bac~~kspac~~e.

Linha 12

Linha 13

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.

Linha 14

Linha 15

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.

Convenção desenvolvedor/Convenção código/Comentários 1.5 (Edição mínima)

2013-01-09T20:00:14Z

Linha 19

=== 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.

Linha 23

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.

}

Linha 31

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.

}

Linha 37

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:

}

Linha 44

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:

}

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

}

Convenção desenvolvedor/Convenção código/Comentários 1.6 (Edição mínima)

2013-01-09T20:00:14Z

Linha 55

=== 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:

}

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**” [5] 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.

Linha 70

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

Convenção desenvolvedor/Convenção código/Comentários 1.7 (Edição mínima)

2013-01-09T20:00:14Z

Linha 73

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

border="1"|= Nome !! Função|

|@author|Nome do autor do código.

|@deprecated|Indica que a o membro em questão (classe, método ou variável) não deve ser usado pois possivelmente será removido em versões futuras.

|@since|Descreve quando o elemento foi adicionado à especificação da API.

|@see|Adiciona um link à seção “Veja também” (“See also”) da documentação.

|@version|Número da versão atual.

|@param|Descreve um ou vários parâmetros de um método, sendo acompanhado por uma descrição.

|@return|Descreve o valor retornado por um método.

|@throws|Indica as exceções verificadas que um dado método dispara.

Convenção desenvolvedor/Convenção código/Comentários 1.8 (Edição mínima)

2013-01-09T20:00:15Z

Linha 93

==== Utilização de comentários no Demoiselle ====

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:

}

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

* ...: definição de um parágrafo de texto;

* ...: texto em negrito;

* ...: texto em itálico;

* ...: 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;

* : quebra de linha no texto.

Convenção desenvolvedor/Convenção código/Comentários 1.9 (Edição mínima)

2013-01-09T20:00:15Z

Linha 99

* }

Linha 100

* }

Linha 101

* }

Linha 102

* }

Linha 103

* }

Linha 104

* }

Linha 105

* }

Linha 99

* ...: definição de um parágrafo de texto;

Linha 100

* ...: texto em negrito;

Linha 101

* ...: texto em itálico;

Linha 102

* ...: texto sublinhado;

Linha 103

* <a>...</a>: inclusão de links de hipertexto para documentos externos (arquivos técnicos, descrição de algoritmos, etc);

Linha 104

* <ol><li>...</li>...</ol>: organiza texto em listas de marcadores;

Linha 105

* : quebra de linha no texto.

Convenção desenvolvedor/Convenção código/Comentários 2.0 (Edição mínima)

2013-01-09T20:00:15Z

Linha 91

==== Utilização de comentários ~~no Demoiselle~~ ====

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

Convenção desenvolvedor/Convenção código/Comentários 2.1 (Edição mínima)

2013-01-09T20:00:15Z

Linha 107

* }

==== 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.

Convenção desenvolvedor/Convenção código/Comentários 2.2 (Edição mínima)

2013-01-09T20:00:15Z

Linha 119

==== 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

}

===== Interface =====

}

===== Enumeração =====

}

===== Anotação =====

}

Convenção desenvolvedor/Convenção código/Comentários 2.3 (Edição mínima)

2013-01-09T20:00:15Z

Linha 138

==== 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.

Linha 140

}

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:

}

Convenção desenvolvedor/Convenção código/Comentários 2.4 (Edição mínima)

2013-01-09T20:00:15Z

Linha 5

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 /** . . . */. [[http://java.sun.com/products/jdk/javadoc/writingdoccomments.html|Comentários Javadoc]] podem ser extraídos para arquivos HTML usando-se a [[http://java.sun.com/products/jdk/javadoc/|ferramenta javadoc]].

Convenção desenvolvedor/Convenção código/Comentários 2.5 (Edição mínima)

2013-01-09T20:00:15Z

Linha 67

Por outro lado, as informações especiais possuem um formato pré-estabelecido. Considere consultar o documento [[http://java.sun.com/products/jdk/javadoc/writingdoccomments.html|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.

Convenção desenvolvedor/Convenção código/Comentários 2.6 (Edição mínima)

2013-01-09T20:00:15Z

Linha 119

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

Linha 120

~~Classe~~

Linha 121

==== Classe ====

Linha 124

Linha 125

===== Interface =====

==== Interface ====

Linha 128

Linha 129

===== Enumeração =====

==== Enumeração ====

Linha 132

Linha 133

===== Anotação =====

==== Anotação ====

Linha 145

}

Convenção desenvolvedor/Convenção código/Comentários 2.7 (Edição mínima)

2013-01-09T20:00:16Z

Convenção desenvolvedor/Convenção código/Comentários 2.8 (Edição mínima)

2013-01-09T20:00:16Z

Convenção desenvolvedor/Convenção código/Comentários 2.9 (Edição mínima)

2013-01-09T20:00:16Z

Linha 125

}

Linha 128

/**

Linha 129

* Structure used to handle pagination of data results on both backend (i.e., persistence) and frontend

Linha 130

* (i.e., presentation) layers in the application.

Linha 131

Linha 132

* @author SERPRO

Linha 133

Linha 134

public interface Pagination {

Linha 127

}

Linha 136

Linha 144