Padrão de Codificação JAVA

Um padrão de codificação visa facilitar o entendimento do código do sistema por qualquer pessoa que conheça e os siga, pois estabelece regras definindo como o código deve ser escrito. Seguir padrões de codificação não é difícil: apenas requer atenção.

ORGANIZAÇÃO DE UM ARQUIVO “.java”

  • O arquivo tem o mesmo nome da classe pública que o contém. Não se define mais de uma classe por arquivo, exceto para as classes internas.
  • Arquivos com mais de 2000 caracteres devem ser evitados.

A linguagem java impõe a seguinte organização ao código fonte:

  • Declaração de pacote;
  • Instrução de importação;
  • Declarações de classes;

A seqüência de declarações recomendada nos arquivos é:

  • Comentários de classe;
  • Declarações de pacote;
  • Instruções de importação;
  • Documentação da Classe;
  • Declaração de classes;
  • Variáveis estáticas;
  • Variáveis de instância;
  • Construtores;
  • Métodos;

COMENTÁRIOS DE CLASSE

  • Todos os arquivos fontes iniciam com um comentário no estilo da linguagem C que lista o nome da classe, versão, data e informações de copyright;

Recomendações:

  • Se um arquivo possuir mais de uma classe ou interface, é inserida uma lista com uma pequena descrição de cada classe ou interface que compõe o arquivo;
  • É recomendável uma explicação que justifique a declaração de mais de uma classe por arquivo, pois Java só permite uma classe pública por arquivo, dificultando a busca de classes não públicas;
  /*
  * Nome da classe
  *
  * Informações de versão
  *
  * Data
  *
  * Copyright
  */

   * Cliente.java
   * Versão: <versaoDoArquivo>
   * Data de Criação : 01/09/2009
   * Copyright (c) 2009 CADT/IFPE.
   * Coordenação de Avaliação e Desenvolvimento de Tecnologias (http://reitoria.ifpe.edu.br)
   * IFPE - http://www.ifpe.edu.br
   * Módulo <nomeDoModulo>
   * Todos os direitos reservados.
  *
  * Este software, em conjunto com os demais módulos do
  * DADT, foi desenvolvido com o objetivo de
  * prover ao IFPE instrumentos e ferramentas que
  * possibilitem o exercício de sua função definidora de
  * políticas, supervisora, estimulando um processo
  * contínuo de avaliação, monitoramento, modernização e
  * transparência.
  */

DECLARAÇÕES DE PACOTE

  • Tem que ser a primeira declaração válida;
  • Todas as letras minúsculas;
  • Não devem conter caracteres especiais, como underscores, ou caracteres específicos de um idioma;
  • Segue o padrão de nomeação das URLs, só que invertido.

Ex: br.edu.ifpe.reitoria.dadt.<nomeDoModulo>.<pacotes>

INSTRUÇÕES DE IMPORTAÇÃO

  • Declaração de Importação

Ex: import java.awt.peer.CanvasPeer;

DECLARAÇÃO DE CLASSE OU INTERFACE

  • Começa com letra maiúscula seguida por minúsculas. Exceto nos casos que a sua abreviação seja mais sugestiva que o nome completo;

Ex: DVD.java ou XML.java

  • Devem ser nomeadas como substantivos;
  • O nome da classe é sempre no singular;
  • Quando a palavra for composta, a separação entre elas é feita por uma letra maiúscula;
  • Não se usa artigos, preposições para conectar substantivos e adjetivos, nem caracteres específicos de uma língua como é o caso do “ç” e os acentos da língua portuguesa;

Ex: Conta, ContaEspecial, LinkedHashMap

A chave de abertura “{” deve aparecer na mesma linha da declaração da classe;
Para efeito de legibilidade, sempre que possível, o parâmetro de retorno deve ser movido para o final do método;

 public class DVDDatabase {
  • Documentação de classes ou interfaces usando Javadoc;

Cada classe começa com um comentário

/** ... */

descrevendo:

  • O propósito da classe;
  • Instruções de uso;
  • E, opcionalmente, alguns exemplos para facilitar o uso da mesma;
  • Em seguida, têm-se lembretes sobre possíveis melhoramentos e defeitos existentes na classe;
  • No final do comentário, adiciona-se o nome dos núcleos responsáveis e referências úteis para o entendimento da classe;
  • Em seguida, tem-se a declaração do nome da classe;
  /**
   * Descrição da classe
   *
   * Exemplo de uso:
   * <pre>
   *    algum Código
   * </pre>
   *
   * Limitações:
  *
  * @author
  * @version
  * @see java.awt.Component
 */
  /**
  * O método main na classe DOSClient possibilita as seguintes
  * funções:
  *  <ul>
  *    <li> Exibe todos os DVDs do Banco de Dados.</li>
  *    <li> Adiciona um DVD no banco de dados. </li>
  *    <li> Remove um DVD do banco de dados. </li>
  *    <li> Modifica o DVD, sendo localizado pelo código. </li>
  *    <li> Tenta alugar um DVD. </li>
 *    <li> Devolução de um DVD alugado. </li>
 * </ul>
 *
 * Limitações: Este programa apresenta uma interface de console que poderá ser substituída por uma interface Swing.
 *
 * @author Anderson Moreira
 * @version 2.0
 * @see sampleproject.db.DVDDatabase
 */
 public class DOSClient {

Após a documentação e a declaração do nome da classe. As declarações dentro de uma classe seguem, respectivamente, a ordem apresentada:

  • Constantes;
  • Variáveis de classe (estáticas);
  • Variáveis de instância;
  • Construtores;
  • Métodos de classe (estáticos);
  • Métodos de instância;
  • Quanto aos modificadores de acesso, primeiro declaram-se as variáveis públicas, depois as protegidas, as sem modificadores, e, por último, as privadas;

Documentação De Interfaces

As declarações de interface seguem a ordem apresentada:

  • Comentários da interface
  /** ...*/
  • Declaração da Interface;
  • Constantes: na seguinte ordem públicas, protegidas, sem modificadores (pacote), privadas;
  • Métodos: os métodos devem ser agrupados por funcionalidade;

Recomendações sobre a utilização de constantes, variáveis de classe e de instância:

  • Constantes – para definir uma constante uma variável deve-se rotular como estática e final;
  • Escritas com todas as letras maiúsculas;
  • Quando composta por duas ou mais palavras a separação é feita por um underscore ( _ );

Ex: TAXA, VALOR_MEDIO

  • A SUN sugere as seguintes regras de nomeação:
  • Atributos (variáveis) – escritas com letras minúsculas;
  • Mesmo podendo iniciar com ( _ ou $) não o faça;
  • E somente variáveis temporárias devem usar nome com apenas um caractere. Quando a palavra for composta, a separação entre elas é feita por uma letra maiúscula;
saldo     // Correto
strTitulo // Correto
floatSaldo// Correto. Palavras reservadas podem ser
          //  usadas como parte do identificador
lâmpada   // Correto, mas inadequado
User_name // Correto, mas não segue as regras de nomeação

Recomendações:

  • Fazer uma declaração por linha.
int nivel; // nível de indentação
int tamanho;  // tamanho da tabela
  • Documentação de uma Variável de Instância
 /**
  * This number uniquely identifies a DVD.
  */
 private String upc; // Holds the record UPC identification
 /**
   * Stores the release date of the film in month /day/ year format.
   */
 private Date year = new Date(); // Holds the movie's release date

MÉTODOS

  • Métodos construtores devem ser listados antes de métodos estáticos e de instâncias;
  • Na assinatura dos métodos não deve haver espaços entre o nome do método e o parêntese de abertura “(“;
  • A chave de abertura “{” deve aparecer na mesma linha da declaração do método;
  • Os métodos são agrupados por funcionalidade e não pela forma de acesso ou sua condição de estático ou de instância;
  • Métodos de acesso a atributos iniciam com get ou set e finalizam com o nome da variável tendo a primeira letra da variável maiúscula;
  • Métodos: Tem a mesma regra das variáveis;
  • Normalmente são verbos no infinitivo representando a utilidade do método, com exceção dos métodos que retornam um boolean, que devem começar com um verbo no presente;
  • Não se utiliza nenhum caractere especial (ç, é, ã, …);
  • Os nomes não devem ser abreviados (torna o código mais fácil de compreender);

Exemplos de nomes de métodos:

 void adicionarLivro(Livro livro)
 void removerLivro(Livro livro)
 boolean existeUsuario(int codigoUsuario)
 double getSaldo() // metodo de acesso
 void setNome(String nome)// metodo modificador

Documentação De Métodos

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 possam levantar;

  /**
   * Locates a DVD using the upc identification number.
   *
   * @param upc The UPC of the DVD to locate.
   * @return The DVD object which matches the upc.
   * @throws IOException Indicates there is a problem
   * accessing the data.
   * @throws ClassNotFoundException Indicates the DVD class
   * definition cannot be found.
  */
  public  DVD getDVD(String upc) throws IOException,
                                 ClassNotFoundException {
         return retrieveDVD(upc);
  }

Recomendações

  • Caso a decisão de visibilidade do método possa ser questionada, documenta-se a razão pela qual foi tomada esta decisão;
  • Se necessário, são declaradas ao final do comentário referências a outras classes e métodos, assim como, a data da criação do método;

PADRÕES DE ESPAÇAMENTO (RECUO; COMPRIMENTO E QUEBRA DE LINHA; ESPAÇOS EM BRANCO)

Recuo

  • Cada nível de recuo deve ter quatro espaços;
  • O início de comentários de declarações de pacote, instruções de importação, declaração de interfaces e classes não devem ser recuados;
  • Variáveis estáticas, variáveis de instância, construtores, métodos e seus respectivos comentários devem ser recuados em um nível;
  • Dentro de construtores e métodos as variáveis locais, instruções e seus comentários devem ser recuados em um nível;
  public class Indent {

 static int staticVar = 7;

  public Indent() { }

  public static void main(String [] args) {

  int x = 0;

 for(int z=0; z<7; z++) {
             x = x + z;
 if (x < 4) {
                 x++;
             }
         }
     }
 }

Comprimento e Quebra de Linha

  • A regra geral é que uma linha não pode ter mais que 80 caracteres;
  • Algumas diretrizes para fazer a quebra de linha;
  • Insira a quebra depois de vírgulas;
  • Use a quebra antes de um operador;
  • A nova linha é alinhada com o começo da expressão do mesmo nível da linha anterior;
 /* exemplo de uma quebra de linha */
 System.out.println(((x * 42) + (z - 343) + (x % z ))
                    + numberOfParsecs);
 /* example de quebra de linha para método */
 x = doStuffWithLotsOfArgs(coolStaticVar, instanceVar,
 numberOfParsecs, reallyLongShortName, x, z);

Espaços em Branco

  • São usados para tornar o código mais legível e menos amontoado;
  • Use uma linha em branco entre;
  • Métodos e construtores;
  • Depois da última variável de instância;
  • Dentro de um método entre variáveis locais e a primeira instrução;
  • Dentro de um método para separar segmentos lógicos de código;
  • Antes de comentários de uma linha ou bloco;
  • Use duas linhas em branco entre seções maiores do código fonte;
  • O pacote, as instruções de importação, a classe ou a interface;

Use espaços em branco:

  • Entre operadores binários
a += c + d;    a = (a + b) / (d * c);
  • Depois de vírgula em uma lista de argumentos
resultado = soma(arg1, arg2);
  • Depois de expressões em uma instrução for
for (exp1; exp2; exp3) {
    comandos;
}
  • Entre uma palavra reservada e um parêntese
while (true) {
    comandos;
}
  • Depois de um cast
livro = (Livro) objeto.getMidia();

EXPRESSÕES E BLOCOS DE COMANDO

Expressões

  • Expressões simples:
  • Cada linha deve conter uma instrução.
contador++;           // Correto
indice--;             // Correto
contador++; indice--; // Evitar!
  • Comando return:
  • Uma sentença return com valor de retorno não utiliza parênteses, a menos que a sentença fique mais clara.
return lista.size();
return (tam > MAX ? tam : VALOR_PADRAO)

Comando if-else

  • É usado com as chaves – “{ }” – para evitar ambigüidade no escopo do comando.
  • Estilos de formatação:
 if (condicao1) {
    comandos;
 } else if (condicao2) {
    comandos;
 } else {
    comandos;
 }

Estrutura switch

 1 switch (variavel) {
 case ABC:
         comandos;
  break;
  case DEF:
          comandos;
  break;
  case XYZ:
          comandos;
 break;
 default:
         comandos;
break;
}

PREFIXOS (OBJETIVO: MANTER A UNIFORMIDADE DO CÓDIGO)

Prefixo para objetos da API JDBC

Prefixos para componentes de interface gráfica

  1. Adilson Benevides Jan 15th, 2013 @ 15:21 | #-49

    Excelente Post!!!!!!!!

  2. anderson Jan 24th, 2013 @ 18:42 | #-48

    Obrigado!

  3. Antonio Jul 13th, 2013 @ 04:07 | #-47

    Olha java é um código muito utilizado por aplicações complicadas mas uteis por isso deve se adequar as realidades do fundo internacional de aplicações de aviões e com mais debate a utlização da ferramenta. O artigo é bom e já uso nos sistemas de submersão aqui de minha casa.

Comments are currently closed.
Trackbacks & Pingbacks ( 0 )
  1. No trackbacks yet.