Mudanças entre as edições de "Manual do Desenvolvedor"
De Grupo Acert
| Linha 44: | Linha 44: | ||
/** | /** | ||
| − | + | * Descrição da classe | |
| − | + | * // | |
| − | + | * Exemplo de uso: | |
| − | + | * <pre> | |
| − | + | * algum Código | |
| − | + | * </pre> | |
| − | + | * // | |
| − | + | * Limitações: | |
| − | + | * // | |
| − | + | * @author <nome do autor> | |
| − | + | * @version <versão da classe> | |
| − | + | * @see br.gov.agricultura.Componente | |
| − | + | */ | |
| + | |||
| + | == Documentação de um método == | ||
| + | |||
| + | Todo método contém um cabeçalho de documentação que fornece informações suficientes para seu entendimento e uso adequado. Inicialmente, documenta-se o que o método faz e porque faz. Após isto, relaciona-se todos os parâmetros necessários para chamar o método, sua cláusula de retorno, e as possíveis exceções que pode levantar. | ||
| + | |||
| + | Exemplo: | ||
| + | |||
| + | /** | ||
| + | * Consulta dados de pessoa física. | ||
| + | * | ||
| + | * @param cpf CPF da pessoa a ser consultada. | ||
| + | * @return entidade PessoaFisica. | ||
| + | * @see PessoaFisica | ||
| + | * @throws IOException Indica que os dados passados são | ||
| + | * inválidos. | ||
| + | * @throws ClassNotFoundException Indica que a classe PessoaFisica | ||
| + | * não foi encontrada. | ||
| + | */ | ||
| + | public PessoaFisica consultaPorCPF (String CPF) throws IOException, | ||
| + | ClassNotFoundException { | ||
| + | ….. | ||
| + | return pessoaFisica; | ||
| + | } | ||
| + | |||
| + | == Documentação de uma sessão do código == | ||
| + | |||
| + | O objetivo deste tipo de comentário é documentar um procedimento especial existente no código. Como regra, é obrigatório seu uso nos casos em que mesmo visualizando os comandos algum desenvolvedor possa ainda não atentar para seu significado, ou para, chamar a atenção sobre algum procedimento que não tenha seu entendimento simplificado. | ||
| + | |||
| + | === Alertas === | ||
| + | |||
| + | É recomendação a utilização de alertas no formato “\\TODO: xxxxx” para indicar pontos de atenção dentro do código. A ferramenta Eclipse possui um conjunto de itens de tarefas que é retirado dos itens destes alertas. Opcionalmente no projeto pode-se utilizar neste padrão o formato “\\TODO: (<login>) xxxx” para indicar que uma mensagem é para um integrande da equipe especificado pelo login. | ||
