Exibir código-fonte para Manual do Desenvolvedor

== Introdução ==

Este documento tem por objetivo orientar a codificação de sistemas. Os assuntos que serão abordados trata a sistemática de adoção de padrões de codificação, tratamentos de exceções e diretrizes a serem adotadas. Todas as definições deste documento se baseia na codificação utilizando linguagem JAVA.

== Organização e Estilo do Código ==

As classes Java possuem o seguinte padrão de codificação:

* Documentação da classe: comentário com informações sobre as classes: objetivo, autor, data, etc.
* Constantes: área opcional declarando constantes a serem utilizadas na própria classe.
* Variáveis de classe (estáticas): utilizadas para input/output de informações externas às classes e de forma unificada (escopo global) entre todas as instâncias da mesma classe.
* Variáveis de instância: utilizadas para input/output de informações externas às classes.
* Construtores: utilizado para definição de métodos de inicialização da classe;
* Métodos de classe (estáticos): são métodos utilizados para operações com a classe e não com o objeto (classe instanciada). Por exemplo: Math.sqrt(2.0);
* Métodos de instância: métodos para operações com valores do objeto (classe instanciada).

== Tipos de visibilidade ==

Para os tipos definidas no Java, as seguintes visibilidades dos métodos/variáveis são possíveis:

'''Private''' - Somente métodos declarados na classe podem acessar esses atributos, esses atributos são encapsulados pelo uso do private e devem ser acessados através de métodos públicos de acesso.

* Use essa visibilidade para todos os atributos de uma classe.
* Use essa visibilidade para todos os métodos de "apoio" de uma classe.

'''Protected''' - Somente métodos declarados na classe, ou qualquer subclasse, ou qualquer classe existente no mesmo pacote poderão acessar.

'''--Default --''' Somente métodos declarados na classe ou qualquer classe que esteja no mesmo pacote. O uso do default se faz pela ausência de qualquer keyword para especificar visibilidade.

'''Public''' - Todas as classes podem acessar.

== Documentação da classe ==

Cada classe começa com um comentário “/** ... */” descrevendo:

* O propósito da classe;
* Instruções de uso;
* Exemplos de uso (opcional);
* Informações sobre possíveis melhoramentos, defeitos existentes ou manutenções efetuadas na classe;
* Nome dos autores;
* Referências úteis para o entendimento da classe.

Em seguida, tem-se a declaração do nome da classe que faz parte da codificação do sistema.

 /**
  * 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.