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.

<nowiki>
<pre>
 /**
  * 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
  */
</pre>
</nowiki>

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

== Regras de Nomeação ==

4.1Regra Geral pág. 10 até pag. 11 (5.Declaração)

== Expressões e Sentenças ==

Check Style

== Recomendações ==

'''Variáveis que alocam objetos utilizando classes de I/O devem ser desalocadas explicitamente'''

Os métodos que utilizam a alocação de variáveis com objetos da classe I/O deve ter a responsabilidade de desalocar estas variáveis. Como regra, as classes que abrirem recursos devem ter a responsabilidade de fecha-los. Também valendo para a alocação.

== Evitar o armazenamento de coleções como variáveis estáticas ==

Objetos que representem coleções podem armazenar vários outros objetos, fazendo com que possa ocorrer memory leaks. O armazenamento de objetos em coleções estáticas serão referenciados por essa coleção por todo o ciclo de vida do programa, se estes objetos não forem removidos explicitamente da coleção o coletor de lixo não vai remove-los.

Exemplo

package com.acme.dados;
import java.util.ArrayList;
public class PessoaFisicaHelper {
public static ArrayList colecao = new ArrayList (); // NÃO FAZER
public void add(Pessoa p) {
colecao.add(p); // pessoa nunca mais será liberado
}

NOTA: Se for extremamente necessário este tipo de armazenamento, limitar a quantidade de objetos armazenados. Este tipo de necessidade deve ser avisado e planejado antecipadamente.

== Tratamento de Erros e de Exceções ==

Por definição:

* Exceções - É uma ocorrência que altera o fluxo do programa. As exceções podem ocorrer por falhas de hardware, problemas no acesso a recursos e execução de regras no sistema. Existem 2 tipos de exceção na prática:
** Exception - exceções verificadas (checked exceptions) pelo compilador. As exceções verificadas que um método pode lançar devem fazer parte da sua assinatura. Por exemplo, se um método pode lançar a exceção IOException, ele precisa declarar este fato na sua assinatura, senão um erro em tempo de compilação é assinalado.
** RuntimeException - são exceções não verificadas pelo compilador. Sendo assim, não é requisito declarar uma cláusula try{} e catch{} e nem constar na assinatura do método.
* Erros – são problemas que acontecem e que não são previstos, por exemplo: tipos, overflow, null. ex.: estouro da memória.

== Construção de Classes ==

=== Evitar assinatura de métodos com mais de 5 parâmetros ===

Como padrão não utilize mais de 5 parâmetros na assinatura da classe. Quando isso tiver que acontecer, crie um objeto para encapsular os dados necessários de forma consistente.

=== Utilização de métodos estáticos com operador de escopo ===

Utilizar sempre o operador de escopo para acesso a métodos estáticos. Por exemplo: PessoaFisica.metodoEstatico(p1);

=== Evitar a chamada de métodos que não sejam final, estáticos ou privados dentro de construtores ===

O objetivo do construtor é inicializar um objeto. Se o método puder ser acessado por uma subclasse, poderá ser feito um override, gerando um resultado não esperado.

=== Quantidade de colunas por linha ===

Não ultrapassar a marcação 80 colunas do eclipse

== Encapsulamento e Controle de Acesso ==

=== Evite a utlização de métodos synchronized ===

A utilização de métodos synchronized deve ser evitado. Sua utilização é restrita e deve ser sinalizado com o responsável pela arquitetura. Se tiver que ser utilizado, deve ser evitada a utilização destes métodos em loops.

=== Utilizar padrão “peso mosca” para instanciamento de objetos em variáveis de instância ===

Sempre que possível utilizar o padrão peso mosca para instanciamento de variáveis de instância que armazenam objetos principalmente. Isto facilita a manutenção, detecção de erros e possíveis evoluções no sistema.

Exemplo

public class Documento{
private Documento documento;
public Documento getDocumento(){
if(documento==null){
documento = new DocumentoTipo();
}
return documento;
}

== Estruturas de Controle ==

=== Evitar a utilização de else em statements do tipo if ===

Para melhor clareza de código evite a utilização de complementos “else” em estruturas de decisão. Para casos em que haja uma necessidade extrema utilizar o “else if" ao invés do “else” sozinho.

=== Utilização do statement break em estruturas de código ===

Como definição, a utilização de break será permitida em estruturas switch. E em estruturas de laço (for) com teste de saída. Por exemplo:

for(int i=0;i<ponto; i++){
if(item[i] == ‘A’){
resposta = item[i];
break;
}
}

== Não utilizar blocos catch com corpo vazio ==

A utilização de blocos catch com corpo vazio leva a erros inexplicáveis dentro do código. Evite sempre a utilização de tratamento específico nas camadas internas sem o repasse das exceções para as camadas externas ao sistema, onde o erro será efetivamente logado e/ou apresentado ao usuário.

== Diversos ==

=== Escrever no código um statement por linha ===

Como boa prática manter sempre uma sentença (statement) por linha em um programa.