Padrão de Desenvolvimento - Documentação

Dentro do projeto REDOME o padrão de codificação exige que haja comentários para documentação de todo o projeto. Havendo este tipo de descrição facilitará o entendimento do time sobre o que faz cada classe e cada método sem que seja necessário entrar em contato com o autor do código e então perguntar sobre a funcionalidade em questão.

Anotações para documentação

Para documentar as classes e métodos é necessário que utilize as anotações abaixo:

Comentários de classes e interfaces

@author - autor do elemento.

@version - número da versão atual.

Comentários de métodos

@param - descreve os parâmetros de um método acompanhado por uma descrição.

@return - descreve o valor retornado por um método.

@throws - indica as exceções que um dado método dispara com uma descrição associada.

Comentários de serialização

@serial - para documentar a serialização de objetos.

Níveis de documentação

Para gerar a documentação será necessário que hajam comentários tanto nas classes quanto nos métodos gerando assim dois níveis de comentários que são os seguintes:

Primeiro nível de comentários

O primeiro deles seria de nível de Classes, Interfaces e Enuns. Para este nível o tipo de comentário que deverá ser inserido é o seguinte:

import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; /** * Classe utilizada para realizar as interações com o banco de dados. */ public class ConexaoBD { }

Obs.: Repare que no código acima houve uma descrição da Classe sobre aquilo que ela faz utilizando “/**/ “ e não com outro tipo de comentário. Dentro da descrição deve-se ter atenção em descrever exatamente o que esta classe é especialista em fazer de forma que quem leia tenha pleno entendimento sobre o seu conteúdo.

Segundo nível de comentários

O segundo nível de comentários é o que será utilizado nos métodos. TODOS os métodos que tem a visibilidade como PUBLIC ou PROTECTED e os métodos de TESTE deverão ser documentados. Sendo assim segue a lista de anotações para documentação de métodos:

import java.sql.Connection; import java.sql.DriverManager; import java.sql.SQLException; /** * Classe utilizada para realizar as interações com o banco de dados. */ public class ConexaoBD { /** * Método construtor. * Você deve utiliza-lo para conectar a base de dados. * @param usuario usuário do banco de dados * @param senha senha do usuário de acesso * @param ipDoBanco endereço IP do banco de dados * @param nomeDaBase nome da base de dados * @throws SQLException * @throws Exception * @author Cristiano Camilo */ public ConexaoBD(String usuario, String senha, String ipDoBanco, String nomeDaBase) throws SQLException , Exception { Class.forName("com.mysql.jdbc.Driver"); Connection conn = DriverManager.getConnection("jdbc:mysql://" + ipDoBanco + "/" + nomeDaBase, usuario, senha); System.out.println("Conectado ao banco de dados."); } //Outros métodos }

Note que na classe acima foram usadas as anotações de @param para os parâmetros, a de @throws para as exceções e @author para o nome do autor de forma totalmente condizente com a assinatura do método. Fazendo desta forma quando este método for utilizado a própria IDE mostrará o seguinte:

conexao.ConexaoBD(String usuario, String senha, String ipDoBanco, String nomeDaBase) Método construtor. Você deve utiliza-lo para conectar a base de dados. Parameters: usuario usuário do banco de dados senha senha do usuário de acesso ipDoBanco endereço IP do banco de dados nomeDaBase nome da base de dados Throws: SQLException Exception @author Cristiano Camilo