Padrão de Desenvolvimento - Documentação
Voltar
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.
Índice
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
|
