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.

<pre>
 /**
  * Descrição da classe.
  *
  * Exemplo de uso:
  * &lt;pre&gt;
  *    algum Código
  * &lt;/pre&gt;
  *
  * Limitações:
  *
  * @author <nome do autor>
  * @version <versão da classe>
  * @see br.exemplo.Componente
  */
</pre>

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

<pre>
/**
 * Consulta dados de pessoa física.
 *
 * @param
 *     CPF CPF da pessoa a ser consultada.
 * @return
 *     Entidade PessoaFisica.
 * @throws
 *     IOException Indica que os dados passados são inválidos.
 * @throws
 *     ClassNotFoundException Indica que a classe PessoaFisica não foi encontrada.
 * @see br.exemplo.PessoaFisica
 */
public PessoaFisica consultaPorCPF(String CPF) throws IOException, ClassNotFoundException {
     ...
     return pessoaFisica;
}
</pre>

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

O Java não tem limite para o nome de classes, métodos ou variáveis. Seguem algumas regras a serem adotadas para compor os nomes:

* '''Constantes:''' use sempre letras maiúsculas separando os nomes por underscore. Por exemplo: MAX_VALUE. O nome da constante deve ser claro e sua definição deve pertencer a uma classe cujo objetivo tenha afinidade com a função da constante. Também é utilizada a regra para utilização dos tipos enumerados. <p> Nota: Constantes são variáveis para serem definidas como final e static. Em geral as constantes devem ser utilizadas para representar literais.</p>

* '''Variáveis privadas e parâmetros:''' utilize letras minúsculas para o primeiro nome. Os nomes devem estar em português e fazer sentido para a função da variável. Eles serão compostos de tantos nomes quanto forem necessários emendados entre si (sem espaços) e sem utilizar o underscore (_) respeitando um máximo de não mais de 30 caracteres. Não use nomes abreviados. <p> Nota: O nome da variável deve ser totalmente legível.</p>

* '''Métodos:''' use letra minúscula no primeiro nome. Os nomes devem estar em português e fazer sentido para o objetivo do método. Eles serão compostos de tantos nomes quanto forem necessários emendados entre si (sem espaços) e sem utilizar o underscore (_). Não use nomes abreviados. A utilização do português como padrão se excetua na utilização de prefixos já comumente utilizados em programas e que tem um contexto já bem definido como por exemplo:

<blockquote>
{| border=1 cellspacing=0 cellpadding=5
|-
! Prefixo
! Função
|-
| get
| Para acessors de leitura de variáveis de classes.
|-
| set
| Para acessors de gravação de variáveis de classes.
|-
| on
| Utilizado para indicar métodos que possuem a funcionalidade de se comportar como eventos
|-
| is
| Métodos que fazem teste e retornam um valor booleano
|}
</blockquote>

* '''Classes e interface:''' use letra maiúscula na primeira letra do nome. Use nomes descritivos. Para interfaces, o nome deve possuir o prefixo I (letra i maíucula)

<blockquote>
{| border=1 cellspacing=0 cellpadding=5
! Sufixo
! Função
|-
| DAO
| Para classes de acesso ao banco de dados
|-
| BO
| Para classes de regras de negócio Business Object
|-
| APS
| Para classes que implementam os casos de uso (Application Services)
|-
| Bean
| Para o serviço (ou comumente bean)
|-
| Remote
| Para a interface remota do Bean
|-
| BD
| Para classes cuja função seja de Busines Delegate action Para as classes que tem o papel de actions da camada de apresentação
|}
</blockquote>

* '''Packages:''' use letras minúsculas em todos os nomes.

* '''Outros objetos:''' os nomes devem estar sempre com todos os caracteres minúsculos.

<blockquote>
{| border=1 cellspacing=0 cellpadding=5
! Extensão
! Função
|- 
| .java
| Classes java no formato de código-fonte
|-
| .properties
| Arquivos de propriedades
|-
| .class
| Classes java no formato de código-objeto
|-
| .jsp
| Páginas de código web para apresentação da aplicação
|-
| .xml
| Arquivos no formato XML
|}
</blockquote>

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

<pre>
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
     }
}
</pre>

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:

<pre>
for(int i = 0; i < ponto; i++) {
     if(item[i] == "A") {
          resposta = item[i];
          break;
     }
}
</pre>

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

== Organização dos projetos ==

'''Nome de projeto:''' o nome do projeto deve estar em minúsculo e composto pela funcionalidade e módulo.

Exemplo:

* logs-core
* logs-view
* hibernate-core

'''Nome de pacotes:''' o nome do pacote deve se composto pela funcionalidade, módulo e recursos.

Exemplo:

* logs.core
* logs.core.model
* logs.core.view
* logs.core.control
* logs.core.util
* logs.core.properties

'''Estrutura de pacotes para testes unitários e funcionais:''' devem estar no diretório ''src-test''

Exemplo:

* logs.core.test
* logs.core.test.model
* logs.core.test.view
* logs.core.test.control
* logs.core.test.util
* logs.core.test.properties


'''Estrutura de diretórios:''' estrutura de diretórios de um projeto web.

: '''<funcionalidade-modulo>'''
:: '''build'''
::: '''producao''' - diretório contendo as configurações do ambiente de produção
:::: '''empresa_x''' - configurações específicas da empresa x
:::: '''empresa_y''' - configurações específicas da empresa y
::: '''homologacao''' - diretório contendo as configurações do ambiente de homologação
:::: '''empresa_x''' - configurações específicas da empresa x
:::: '''empresa_y''' - configurações específicas da empresa y
::: '''teste''' - diretório contendo as configurações do ambiente de testes
:::: '''empresa_x''' - configurações específicas da empresa x
:::: '''empresa_y''' - configurações específicas da empresa y
:: '''src''' - diretório contendo os arquivos fontes do projetos
:: '''src-test''' - contendo os testes unitários e funcionais
:: '''WebContent'''
::: '''resources''' - diretório contendo imagens, scripts e folha de estilos
::: '''WEB-INF'''
:::: '''relatorios''' - arquivos .jasper
:::: '''paginas''' - arquivos .jsp/.xhtml/.html/.ftl
::: '''META-INF'''
::: arquivos .swf