Mudanças entre as edições de "Manual do Desenvolvedor"

De Grupo Acert
Ir para: navegação, pesquisa
(→‎Organização dos projetos)
 
Linha 26: Linha 26:
 
'''Protected''' - Somente métodos declarados na classe, ou qualquer subclasse, ou qualquer classe existente no mesmo pacote poderão acessar.
 
'''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.
+
'''-- 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.
 
'''Public''' - Todas as classes podem acessar.
Linha 43: Linha 43:
 
Em seguida, tem-se a declaração do nome da classe que faz parte da codificação do sistema.
 
Em seguida, tem-se a declaração do nome da classe que faz parte da codificação do sistema.
  
 +
<pre>
 
  /**
 
  /**
−
* Descrição da classe
+
  * 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.
 
  *
 
  *
−
  * Exemplo de uso:
+
  * @param
−
  * <pre>
+
  *     CPF CPF da pessoa a ser consultada.
−
  * algum Código
+
  * @return
−
  * </pre>
+
  *     Entidade PessoaFisica.
−
  * //
+
  * @throws
−
  * Limitações:
+
  *     IOException Indica que os dados passados são inválidos.
−
* //
+
  * @throws
−
  * @author <nome do autor>
+
  *     ClassNotFoundException Indica que a classe PessoaFisica não foi encontrada.
−
  * @version <versão da classe>
+
  * @see br.exemplo.PessoaFisica
−
  * @see br.gov.agricultura.Componente
+
 
  */
 
  */
 +
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

Edição atual tal como às 09h55min de 29 de setembro de 2011

Disponível em "http://wiki.grupoacert.com.br/index.php?title=Manual_do_Desenvolvedor&oldid=208"