Você está na página 1de 26

Convenções para Codificação Java

Tradução: Jefferson Araujo Bibliografia: Oracle Sun Microsystems

Convenções para Codificação Java Tradução: Jefferson Araujo Bibliografia: Oracle – Sun Microsystems
Convenções para Codificação Java Tradução: Jefferson Araujo Bibliografia: Oracle – Sun Microsystems

Índice

1. INTRODUÇÃO

4

1.1 POR QUE UTILIZAR CONVENÇÃO DE CÓDIGO?

4

1.2 POR QUE UTILIZAR CONVENÇÃO DE CÓDIGO?

4

2. NOMES DE ARQUIVOS

5

2.1 ARQUIVOS DE SUFIXOS

5

2.2 NOMES DE ARQUIVOS COMUNS

5

3. ORGANIZAÇÃO DE ARQUIVOS

5

4. ARQUIVOS-FONTE JAVA

6

4.1 COMENTÁRIOS INICIAIS

6

4.2 DECLARAÇÕES DE PACOTES E IMPORTAÇÕES

6

4.3 DECLARAÇÕES DE CLASSE E DE INTERFACE

7

5. INDENTAÇÃO

8

5.1 COMPRIMENTO DA LINHA

8

5.2 EMPACOTANDO LINHAS

8

6. COMENTÁRIOS

10

6.1

FORMATOS DE COMENTÁRIOS DE IMPLEMENTAÇÃO

10

6.1.1 COMENTÁRIOS DE BLOCO

11

6.1.2 COMENTÁRIOS DE LINHANICA

11

6.1.3 COMENTÁRIOS DE TRILHA

12

6.1.4 COMENTÁRIOS DE FINAL DE LINHA

12

6.2

COMENTÁRIOS DE DOCUMENTAÇÃO

12

7. DECLARAÇÕES

14

7.1 NÚMERO POR LINHA

14

7.2 LOCALIZAÇÃO

14

7.3 INICIALIZAÇÃO

15

7.4 DECLARAÇÕES DE CLASSE E INTERFACE

15

8. DECLARAÇÕES / COMANDOS

16

8.1 COMANDOS SIMPLES

16

8.2 COMANDOS COMPOSTOS

16

8.3 COMANDO DE RETORNO (RETURN)

17

8.4 COMANDOS IF‖, ―IF-ELSE‖, ―IF-ELSE-IF-ELSE

17

8.5 COMANDOS FOR

17

8.6 COMANDOS WHILE

18

8.7 COMANDO DO-WHILE

18

8.8 COMANDO SWITCH

18

8.9 COMANDO TRY-CATCH

19

9.1

LINHAS EM BRANCO

19

9.2

ESPAÇOS EM BRANCO

20

10. CONVENÇÕES DE NOMENCLATURA

21

11. PRÁTICAS DE PROGRAMAÇÃO

23

11.1 FORNECENDO ACESSO À INSTÂNCIA E VARIÁVEIS DE CLASSE

23

11.2 REFERINDO-SE A VARIÁVEIS DE CLASSE E MÉTODOS

23

11.3 CONSTANTES

23

11.4 ATRIBUIÇÕES DE VARIÁVEIS

23

11.5 PRÁTICAS DIVERSAS

24

11.5.1 PARÊNTESES

24

11.5.2 VALORES DE RETORNO

24

11.5.3 EXPRESSÕES ANTES DE ―?‖ NO OPERADOR CONDICIONAL

25

11.5.4 COMENTÁRIOS ESPECIAIS

25

12.

EXEMPLO DE CÓDIGO

25

12.1

EXEMPLO DE CÓDIGO FONTE JAVA

25

1. Introdução

As convenções de código são uma boa prática de programação. Ajudam por exemplo na manutenção de um sistema. A violação dessas ―regras‖ prejudica e muito o entendimento de uma API, por exemplo. Além do mais, com as convenções, podemos produzir um código legível e ―limpo‖, que demonstra qualidade de maneira profissional.

1.1 Por que utilizar convenção de código?

As convenções de código são importantes para os programadores por uma série de razões:

80 % do tempo gasto com o software vai para a manutenção;

Dificilmente um software é mantido por toda sua existência pelo autor original;

As convenções de código melhoram a legibilidade do software, fazendo com que engenheiros entendam o novo código mais rapidamente e por completo;

Se um código fonte de programa deve ser enviado como um produto, é preciso ter certeza que ele está bem embalado, assim como qualquer outro produto.

Obs: Um ponto muito importante. Para que as convenções funcionem, todas as pessoas que escrevem software devem estar de acordo com as convenções, este é um processo que precisa ser divulgado desde a raiz para que TODOS tenham em mente estas boas práticas.

1.2 Por que utilizar convenção de código?

Esse documento reflete o padrão do código da linguagem JAVA apresentado no ―JAVA Language Specification‖, da Sun Microsytems (atual Oracle). As maiores contribuições são de Peter King, Patrick Naughton, Mike DeMoney, Jonni Kannerva, Kathy Walrath e Scott Hommel.

Comentários devem ser enviados através de formulário para:

2.

Nomes de Arquivos

Essa seção lista os sufixos e nomes usados com maior freqüência.

2.1 Arquivos de Sufixos

O Software Java utiliza os seguintes sufixos:

 

Tipo de Arquivo

Sufixo

 

Fonte Java

.java

Código de Byte Java

.class

Nome do Arquivo

 

Uso

 

O nome preferido para criação de arquivos. Usa-se GNUmake para construção do software.

GNUmakefile

 
 

Nome preferido do arquivo que resume o conteúdo de um diretório particular

README

 

2.2 Nomes de Arquivos Comuns

3. Organização de Arquivos

Um arquivo consiste de seções que devem ser separadas por linhas em branco e um comentário opcional identificando cada seção.

Arquivos com mais de 2000 linhas são pesados e devem ser evitados.

Para ver um exemplo de programa Java corretamente formatado, veja o item 12.1.

4. Arquivos-Fonte Java

Cada arquivo-fonte Java contém uma única classe pública ou de interface. Quando classes privadas e interfaces são associadas a uma classe pública, elas podem ser colocadas no mesmo arquivo-fonte da classe pública. A classe pública deve ser a primeira classe ou interface no arquivo.

Arquivos-fonte Java seguem a seguinte ordem:

Comentários Iniciais (ver item 4.1);

Declarações de pacotes e importes; por exemplo:

import java.applet.Applet; import java.awt.*; import java.net.*;

Declarações de classe e de interface (ver item 4.3).

4.1 Comentários Iniciais

Todos os arquivos-fonte devem começar com um comentário ―c-style‖ que lista: nome da classe, versão, data, breve descrição do propósito do programa e direitos autorais. Por exemplo:

/*

*

Nome da Classe:

*

*

Informação da Versão:

*

*

Data:

*

*

Propósito do Programa:

*

*

Direitos Autorais:

*/

4.2 Declarações de Pacotes e Importações

A primeira linha sem comentários da maioria dos arquivos-fonte Java é uma declaração de pacote. Após isso, podem ser realizadas as declarações de importação. Por exemplo:

package java.awt; import java.awt.peer.CanvasPeer;

4.3 Declarações de Classe e de Interface

A quadro a seguir descreve as partes de uma declaração de classe ou de interface, na ordem em que elas devem aparecer. Ver o exemplo do item 12.1 que inclui comentários.

   

Declaração de parte da Classe / Interface

Notas

   

Ver item “6.2 – Comentários de

 

Comentários de

1

documentação de classe

Documentação” para informação

   

/

interface (/**

*/)

do que deve conter este comentário.

2

 

Declaração de classe ou de interface

 

Comentário de

implementação de classe

interface (/**

*/),

/

se

necessário

Esse comentário deve conter qualquer informação a respeito da

3

classe ou da interface não definida no comentário de documentação de classe ou interface.

 
     

Primeiro as variáveis de classes públicas, depois as protegidas, após

 

4

   

isso, o nível de empacotamento (sem modificação de acesso) e, aí sim, a classe privada.

   

Variáveis de classe (estática)

 

5

Variáveis instanciáveis

Primeiro as públicas, depois as protegidas e então as privadas.

6

 

Construtores

 
     

Esses métodos devem ser agrupados por funcionalidade antes do que por escopo ou acessibilidade. Por exemplo, um

7

Métodos

método da classe privada pode estar entre dois métodos públicos. O objetivo é fazer com que a leitura e entendimento do código seja realizado mais facilmente.

     

5. Indentação

Quatro espaços devem ser usados como unidade de indentação. A construção exata de indentação (espaços versus tabulações) não é especificada. Tabulações devem ser estabelecidas com 8 espaços (e não com 4).

5.1 Comprimento da Linha

Evitar linhas com mais de 80 caracteres, desde que estes não sejam manipulados por diversos terminais e ferramentas.

Obs.: Exemplos para uso em documentação deve ter menor comprimento de linha geralmente não mais que 70 caracteres.

5.2 Empacotando Linhas

Quando uma expressão não contiver uma única linha, a sua quebra deve ocorrer de acordo com alguns princípios:

A quebra deve ocorrer após uma vírgula;

A quebra deve ocorrer antes de um operador;

Dar preferência as quebras em níveis mais altos do que as de níveis mais baixos;

Alinhar a nova linha com o começo da expressão no mesmo nível da linha anterior;

Caso as regras acima venham a confundir o código ou espremê-lo contra a margem direita, apenas utilize a indentação de 8 espaços.

Aqui estão alguns exemplos de chamadas a métodos com linhas quebradas:

funcao(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);

variavel = funcao1(longExpression1,

funcao2(longExpression2,

longExpression3));

A seguir estão dois exemplos de quebra de uma expressão aritmética. A primeira é a preferida, desde que a quebra ocorra fora da expressão contida entre parênteses, que é de um nível elevado:

longName1 = longName2 + (longName3 + longName4 - longName5) + 4 * longName6; // Preferida

longName1 = longName2 + (longName3 + longName4 - longName5) + 4 * longName6; // Evitar

A seguir dois exemplos de métodos de indentação de declarações. O primeiro é o caso convencional. O segundo mudaria a 2ª e a 3ª linhas para a direita se for usada a indentação convencional. Ao invés disto identar apenas 8 espaços:

//INDENTAÇÃO CONVENCIONAL someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) {

}

//INDENTAR 8 ESPAÇOS PARA EVITAR IDENTAÇÕES MUITO DISTANTES private static synchronized horkingLongMethodName (int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) {

}

Empacotamento de linhas para declarações "IF" devem geralmente usar a regra de 8 espaços, uma vez que a regra convencional (4 espaços) dificulta a visualização. Por exemplo:

//NÃO USAR ESTA INDENTAÇÃO if ((condition1 && condition2)

|| (condition3 && condition4) ||!(condition5 && condition6)) { //PESSIMO EMPACOTAMENTO

doSomethingAboutIt();

}

//FACILITA PERDER A LINHA

//USAR ESTA INDENTAÇÃO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt();

}

//OU USAR ESTA INDENTAÇÃO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt();

}

Aqui estão três formas aceitáveis de formatar expressões ternárias:

alpha = (aLongBooleanExpression) ? beta : gama;

alpha = (aLongBooleanExpression) ? beta : gama;

alpha = (aLongBooleanExpression) ? beta : gama;

6. Comentários

Os programas Java podem ter dois tipos de comentários: comentários de implementação e comentários de documentação. Comentários de implementação são aqueles

encontrados em C++, delimitados por /*

(também conhecidos como "doc comments") servem apenas para o Java e são

delimitados por /**

HTML utilizando a ferramenta javadoc.

*/,

ou //. Comentários de documentação

*/.

Comentários de documentação podem ser extraídos para

Comentários de implementação são recursos para comentários a respeito do código ou de uma implementação particular. Comentários de documentação são usados para descrever a especificação do código, de uma perspectiva de livre implementação, a ser lida por desenvolvedores que não têm necessariamente que ter o código-fonte à mão.

Comentários devem ser usados para dar uma visão geral do código e fornecer informação adicional, que não é facilmente disponível no próprio código. Comentários devem conter apenas informações relevantes para ler e entender o programa. Por exemplo, não devem ser incluídos como comentários informações sobre como o empacotamento correspondente é feito ou em qual diretório ele se encontra.

Discussão sobre decisões de design não triviais ou não óbvias é apropriada, mas evite a duplicação de informação que está presente no código. É muito fácil comentários redundantes se desatualizarem. Em geral, evite alguns comentários que provavelmente se desatualizarão à medida que o código for se expandindo.

Obs: A freqüência de comentários às vezes reflete a qualidade pobre do código. Quando o programador se sentir compelido a adicionar comentários, deverá ser considerada a possibilidade de reescrever o código para deixá-lo mais claro.

Comentários não devem ser fechados em grandes quadros desenhados com asteriscos ou outros caracteres. Comentários nunca devem incluir caracteres especiais como caractere de alimentação de formulário ou retorno de espaço.

6.1 Formatos de Comentários de Implementação

Programas podem ter quatro estilos de comentários de implementação: De Bloco, Linha-Única, Em Trilha e Fim da Linha.

6.1.1 Comentários de Bloco

Comentários de bloco são usados para prover descrições de arquivos, métodos, estruturas de dados e algoritmos. Comentários de bloco devem ser usados no início de cada arquivo e antes de cada método. Eles também podem ser usados em outros lugares, como dentro de métodos. Blocos de comentários dentro de uma função ou método devem ser identados no mesmo nível da descrição do código. Um bloco de comentário deve ser precedido por uma linha em branco para determinar a separação do resto do código. Blocos de comentários possuem um asterisco ―*‖ no início de cada linha exceto na primeira. Por exemplo:

/*

*

Aqui esta um Bloco de Comentário.

*/

Blocos de comentários podem iniciar com /*-, que é reconhecido pelo identador(1) como um início de um bloco de comentário que não deve ser reformatado. Por exemplo:

/*-

*

Este é um bloco de comentário com algumas formatações

*

muito especiais que eu quero identador(1) ignore.

*

*

um

*

dois

*

três

*/

Obs: Se o identador(1) não for utilizado, não deve ser usada a combinação /*- no código nem devem ser feitas outras concessões, pois sempre há a possibilidade de outro programador utilizá-lo em seu código.

Ver também o item ―6.2 Comentários de Documentação‖.

6.1.2 Comentários de Linha-Única

Pequenos comentários podem aparecer em uma linha única identados no nível do código que segue. Se um comentário não pode ser escrito em uma linha única, deve ser seguido o formato do comentário em bloco (Ver item 6.1.1 Comentários de Bloco). Um comentário de linha única devem ser precedidos por uma linha em branco. Segue abaixo um exemplo de um comentário de linha única utilizando codificação Java:

if (condition) { /* Manipular a condição. */

}

6.1.3 Comentários de Trilha

Pequenos comentários podem aparecer na mesma linha em que o código esta sendo descrito, mas devem ser deslocados longe o suficiente para separá-los das declarações. Se mais de um pequeno comentário aparecer em um pedaço de código, todos eles devem ser identados com o mesmo parâmetro de tabulação.

Segue abaixo um exemplo de um comentário de linha única utilizando codificação Java:

if (a == 2) { return TRUE;

/* caso especial */

}

else { return isprime(a);

/* usa a condição a */

}

6.1.4 Comentários de Final de Linha

O delimitador de comentário ―//‖ pode se referir a uma linha inteira ou pode ser utilizado para continuação de uma linha anterior em uma nova linha (ou seja, comentar parte de uma linha). Não deve ser usado em múltiplas linhas consecutivas para textos de comentários; entretanto, pode ser usado em múltiplas linhas consecutivas para comentar seções de código. Segue abaixo exemplos utilizando estes três estilos utilizando a linguagem Java:

if (foo > 1) { // Faça um duplo-flip.

}

else { return false;

// Explicar o porque aqui.

}

//if (bar > 1) { //

//

// Faça um triplo-flip.

//

//}

//else

//

return false;

6.2 Comentários de Documentação

Obs: Ver o item ―12.1 Exemplo de arquivo-fonte Java‖ para exemplos de formatos de comentários descritos aqui.

Para maiores detalhes, ver ―How to Write Doc Comments for Javadoc‖ que inclui informação em tags de comentários de documentação (@return, @param, @see) no endereço abaixo:

Para maiores detalhes sobre comentários de documentação e javadoc, veja a página do javadoc em:

Comentários de documentação descrevem classes Java, interfaces,

construtores, métodos e campos. Cada comentário de documentação é

mantido dentro dos delimitadores de comentário /**

por API (Classe, interface, construtor, método ou campo). Esse comentário

deve aparecer imediatamente antes da declaração. Por exemplo:

*/,

com um comentário

/** * O exemplo de classe que provê */ class Exemplo {

Perceba que classes e interfaces não estão identadas, enquanto seus membros estão. A primeira linha do comentário de documentação (/**) para classes e interfaces não é identada; cada linha de comentário de documentação subseqüente possui um espaço de indentação (para verticalmente se alinhar aos asteriscos). Membros, incluindo construtores, possuem quatro espaços para a primeira linha de comentário de documentação e cinco espaços para as demais.

Se for preciso dar informação sobre uma classe, interface, variável ou método que não é apropriado para documentação, deve ser utilizado um comentário de bloco (ver item 6.1.1) ou comentário de linha-única (ver item 6.1.2) imediatamente após a declaração. Por exemplo, detalhes sobre a implementação de uma classe devem ir em um tipo de comentário de bloco seguindo a declaração de classe e não no comentário de documentação da classe.

Comentários de documentação não devem ser posicionados dentro de um bloco de definição de método ou de um construtor, porque Java associa comentários de documentação com a primeira declaração após o comentário.

7. Declarações

7.1 Número por Linha

Uma declaração por linha é recomendada desde que a mesma incentiva a comentar. Em outras palavras,

int nivel;

indentação int tamanho; // tamanho da tabela

// nível de

É preferível:

int nivel, tamanho;

De forma alguma variáveis e funções devem ser declaradas na mesma linha. Por exemplo:

long dbaddr, getDbaddr(); // ERRADO!

Também não podemos colocar diferentes tipos de dados na mesma linha. Por exemplo:

int foo, fooarray[];

// ERRADO!

Obs: Os exemplos acima usam um espaço entre o tipo do dado e o identificador. Uma outra alternativa aceitável é a utilização de tabulação. Por exemplo:

int

nivel;

// nível de indentação

int

tamanho;

// tamanho da tabela

Object entradaAtual; // entrada atual da tabela selecionada

7.2 Localização

Coloque as declarações apenas no início dos blocos. (Um bloco é qualquer

código cercado por chaves ―{― e ―}‖.) Não espere para declarar variáveis até

a sua primeira utilização; isso pode confundir o programador descuidado e prejudicar a portabilidade do código dentro do escopo.

void meuMetodo() { int int1;

// início do bloco de método

if (condicao) { int int2;

// início do bloco de “if”

}

}

Uma exceção para esta regra refere-se aos índices de loops do tipo ―for‖, nos quais o Java pode ser declarado na declaração ―for‖:

for (int i = 0; i < maxLoops; i++) {

Evite declarações locais que ocultem declarações no nos níveis superiores. Por exemplo, não declare uma variável com o mesmo nome em um bloco interno:

int count;

func() { if (condicao) { int count;

}

}

//EVITAR!

7.3 Inicialização

Tente inicializar variáveis locais onde elas são declaradas. A única razão para não inicializar uma variável onde elas são declaradas é se o valor inicial da mesma depender de algum processamento que necessite ocorrer primeiro.

7.4 Declarações de Classe e Interface

Quando codificando classes e interfaces Java, o seguinte formato de regras deve ser seguido:

Não colocar espaços entre o nome do método e os parênteses ―(― começando sua lista de parâmetros;

Chave de abertura ―{― deve aparecer no fim da mesma linha de comando da declaração;

Chave de fechamento ―}‖ deve começar a linha identada para coincidir com a sua declaração de abertura correspondente, exceto quando uma declaração nula a chave ―}‖ deve aparecer imediatamente após a chave de abertura ―{―;

class Exemplo extends Object { int ivar1; int ivar2;

Exemplo(int i, int j) { ivar1 = i; ivar2 = j;

}

int metodoVazio() {}

}

Métodos devem ser separados por uma linha em branco.

8. Declarações / Comandos

8.1 Comandos Simples

Cada linha deve conter no máximo um comando. Por exemplo:

argv++; argc--;

// EVITAR!

argv++;

// CORRETO!

argc--;

// CORRETO!

Não use vírgula para agrupar múltiplos comandos a menos que seja por uma razão obvia. Por exemplo:

if (err) { Format.print(System.out, “error”), exit(1); // ERRADO!

}

8.2 Comandos Compostos

Comandos compostos são comandos que contém listas de comandos encapsulados dentro de chaves ―{ comandos }‖. Ver os exemplos a seguir:

Os comandos encapsulados entre chaves devem ser identados um nível acima do comando composto;

A chave de abertura deve estar no fim da linha que começa o comando composto; a chave de fechamento ―}‖ deve começar a linha e estar identado no começo do comando composto;

Chaves são utilizadas em volta de todos os comandos, mesmo comandos simples, quando são parte de uma estrutura de controle, tanto quanto em comandos ―if-else‖ ou ―for‖. Isso torna mais fácil a adição de comandos

sem introduzir erros acidentalmente devido ao esquecimento da inclusão de chaves.

8.3 Comando de Retorno (return)

O comando return com um valor não deve usar parênteses a menos que torne

o valor de retorno mais óbvio de alguma forma. Por exemplo:

return;

return meuDisco.size();

return (size ? size : defaultSize);

8.4 Comandos “if”, “if-else”, “if-else-if-else”

A classe de comandos ―if-else‖ devem ter a seguinte forma:

if (condicao) { comandos;

}

if (condicao) { comandos;

}

else { comandos;

}

if (condicao) { comandos;

}

else if (condicao) { comandos;

}

else if (condicao) { comandos;

}

Obs: Comandos ―if‖ sempre usam chaves ―{}‖. Evite utilizar a forma errada

a seguir:

if (condicao)

comando;

// EVITAR! ESTE TIPO OMITE AS CHAVES {}!

8.5 Comandos “for”

Um comando ―for‖ deve ter a seguinte forma:

for (inicializacao; condicao; atualizacao) { comandos;

}

Um comando ―for‖vazio (um em que todo o trabalho é feito nas cláusulas de inicialização, de condição ou de atualização) deve ter a seguinte forma:

for (inicializacao; condicao; atualizacao);

Quando usado a vírgula nas cláusulas de inicialização ou atualização de um comando ―for‖, evite a complexidade de utilizar mais de três variáveis. Se preciso, utilize comandos separados antes do loop ―for‖ (para cláusula de inicialização) ou no final do loop (para cláusula de atualização).

8.6 Comandos “while”

Um comando ―while‖ deve ter a seguinte forma:

while (condicao) { comandos;

}

Um comando ―while‖ em vazio deve ter a seguinte forma:

while (condicao);

8.7 Comando “do-while”

Um comando ―do-while‖ deve ter a seguinte forma:

do {

comandos; } while (condicao);

8.8 Comando “switch”

Um comando ―switch‖ deve ter a seguinte forma:

switch(condicao) { case ABC: comandos; /* fallsthrough */ case DEF: comandos; break; case XYZ: comandos;
switch(condicao) {
case ABC:
comandos;
/* fallsthrough */
case DEF:
comandos;
break;
case XYZ:
comandos;
break;
default:
comandos;
break;
}

Toda ocorrência de um caso ―falls through‖ (não incluir um comando ―break‖), deve ter adicionado um comentário onde o comando ―break‖ normalmente deveria estar. Isto é mostrado no exemplo acima com o comentário ―/* falls through */‖.

Todo comando ―switch‖ deve incluir um caso padrão (default). O ―break‖ no caso padrão é redundante, mas previne a entrada em uma situação de erro se posteriormente um novo caso for incluído.

8.9 Comando “try-catch”

Um comando ―try-catch‖ deve ter o seguinte formato:

try {

comandos; } catch (ExceptionClass e) { comandos;

}

9. Espaço em Branco

9.1 Linhas em Branco

Linhas em branco melhoram a leitura pela separação de seções de código que estão logicamente relacionadas.

Duas linhas em branco devem sempre ser usadas nas seguintes circunstâncias:

Entre seções dos arquivos-fonte;

Entre definições de classes e interfaces.

Uma linha em branco deve sempre ser usada nas seguintes circunstâncias:

Entre métodos;

Entre variáveis locais em um método e seu primeiro comando;

Antes de um comentário de bloco (ver item 6.1.1) ou de linha-única (ver item 6.1.2);

Entre seções lógicas dentro de um método para melhorar a leitura e entendimento.

9.2 Espaços em Branco

Espaços em branco devem ser usados nas seguintes circunstâncias:

Uma palavra-chave (keyword) seguida por parênteses deve ser separada por um espaço. Por exemplo:

while (true) {

}

Note que um espaço em branco não deve ser usado entre o nome do método e seu parênteses de abertura. Isso ajuda a distinguir palavras- chave (keywords) de chamadas de método.

Um espaço em branco deve aparecer após as vírgulas na lista de argumentos;

Todos os operadores binários (exceto ―.‖) devem ser separados de seus operandos por espaços. Espaços em branco nunca devem separar operadores ―únicos‖, como símbolo de subtração simples (―-―), de incremento (―++‖) ou de decréscimo (―—―) de seus operandos. Por exemplo:

a += c + d;

a = (a + b)

/ (c * d);

a += c + d;

a = (a + b)

/ (c * d);

while (d++ = s++) { n++;

}

prints(“size is “ + foo + “n”);

As expressões em um comando ―for‖ devem ser separadas por espaços em branco. Por exemplo:

for (expr1; expr2; expr3)

Casts devem ser seguidos por um espaço em branco. Por exemplo:

meuMetodo((byte) aNum, (Object) x); minhaFuncao((int) (cp + 5), ((int) (i + 3)) + 1);

10.

Convenções de Nomenclatura

Convenções de Nomenclatura faz com que os programas fiquem mais fáceis de serem lidos. Eles podem também dar informação sobre a função ou o identificador por exemplo, se é uma constante, pacote ou classe que pode ser útil no entendimento do código.

Tipo de

Identificador

Classes

Tipo de Identificador Classes Pacotes Regras para Nomenclatura Os nomes de classe devem ser substantivos, uma
Tipo de Identificador Classes Pacotes Regras para Nomenclatura Os nomes de classe devem ser substantivos, uma

Pacotes

Tipo de Identificador Classes Pacotes Regras para Nomenclatura Os nomes de classe devem ser substantivos, uma
Tipo de Identificador Classes Pacotes Regras para Nomenclatura Os nomes de classe devem ser substantivos, uma

Regras para Nomenclatura

Regras para Nomenclatura
de Identificador Classes Pacotes Regras para Nomenclatura Os nomes de classe devem ser substantivos, uma combinação

Os nomes de classe devem ser substantivos, uma combinação de tamanhos de fonte (fontes maiúsculos e minúsculos) com

de tamanhos de fonte (fontes maiúsculos e minúsculos) com a primeira letra em maiúsculo e as

a

primeira letra em maiúsculo

e

as compostas também em

maiúsculo, as demais seguem em minúsculo. Os nomes de classes devem, sempre que possível, ser simples e descritivos. Usar palavras completas evitando acrônimos e abreviações (a menos que a abreviação seja a forma mais usada e conhecida

do que a palavra longa, como URL ou HTML)

O prefixo de um pacote é

sempre escrito em letras minúsculas em padrão ASCII

e deve ser um dos nomes de

domínio de alto nível atualmente com, edu, gov, mil, net, org ou um dos códigos de duas letras em inglês que identifica os países

de acordo com a especificação ―ISO Standard 3166, 1981‖.

Componentes subseqüentes do nome do pacote variam de acordo com a convenção interna da própria organização. Assim, convenções devem especificar que um certo nome de

Exemplos

class Imposto;

class PesquisaImposto;

de Exemplos class Imposto; class PesquisaImposto; com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese

com.sun.eng

com.apple.quicktime.v2

edu.cmu.cs.bovik.cheese

de Exemplos class Imposto; class PesquisaImposto; com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese
 

diretório de componente é divisão, departamento, projeto, máquina ou login.

 

Interfaces

Os nomes de interface devem seguir o mesmo padrão de nomenclatura dos nomes das classes.

interface ImpostoInterface;

 

interface VeiculoInterface;

Métodos

Os métodos devem ser verbos, com a primeira letra em minúscula e a primeira letra das demais compostas em letra maiúscula.

run();

 

runFast();

getBackground():

Variáveis

Exceto para variáveis, todas as instâncias, classes e classes constantes se formam com a

int

i;

 

char

c;

primeira letra minúscula. As palavras compostas internas devem iniciar com letra maiúscula.

float

meuTamanho;

 

Nomes de variáveis devem ser pequenos mas com um significado. A escolha de um nome de variável deve ser mnemônico ou seja, desenhado para indicar a intenção de seu uso. Os nomes de variáveis com apenas um caractere devem ser evitados, exceto nos casos de variáveis temporárias ―descartáveis‖. Os nomes mais usuais para variáveis temporárias são:

i,j,k,m e n para inteiros; c,d, e e para caracteres.

Constantes

Os nomes de variáveis constantes de classes declaradas e de constantes ANSI devem ser totalmente em letras maiúsculas com as palavras separadas por sublinhado (_). (As constantes ANSI devem ser evitadas para facilitar o d ebugging. ).

static final int MIN_WIDTH = 4;

 

static final int MAX_WIDTH =

999;

static final int GET_THE_CPU =

1;

11.

Práticas de Programação

11.1 Fornecendo Acesso à Instância e Variáveis de Classe

Não faça qualquer instância ou variável de classe publica sem ter uma boa razão. Muitas vezes, variáveis de instância não precisam ser explicitamente obtidas ou definidas muitas vezes o que acontece como um efeito colateral de chamadas de método.

Um exemplo de um apropriado uso de variáveis de instância públicas é o caso quando a classe é essencialmente uma estrutura de dados, sem comportamento próprio. Em outras palavras, se tivesse usado struct ao invés de uma class (se o Java suportasse struct), então seria apropriado fazer instâncias de variáveis públicas de classe.

11.2 Referindo-se a Variáveis de Classe e Métodos

Evite usar um objeto para acessar uma variável de classe (static) ou método. Use um nome de classe ao invés disso. Por exemplo:

classMethod();

//OK

AClass.classMethod();

//OK

AnObject.classMethod();

//EVITAR!

11.3 Constantes

Constantes numéricas (literais) não devem ser codificadas diretamente, exceto para 1, 0 e 1, os quais podem aparecer como valores em contadores de loop do tipo ―for‖.

11.4 Atribuições de Variáveis

Evite atribuir um valor para diversas variáveis em uma única instrução. Dificulta sua leitura. Por exemplo:

fooBar.fChar = barFoo.lchar = „c‟;

// EVITAR!

Não use operadores de atribuição em um lugar onde pode ser facilmente confundido com um operador de igualdade. Por exemplo:

if (c++ = d++) {

}

// EVITAR! Java não permite!

Deve ser escrito desta forma:

if ((c++ = d++) != 0) {

}

Não use atribuições embutidas em uma tentativa de melhorar a performance de execução do código. Isso é tarefa do job de compilação, e além disso, isso na verdade raramente ajuda. Por exemplo:

d

=

(a

=

b

+ c) +

r;

// EVITAR!

Deve ser escrito da seguinte forma:

a

= b + c;

d

= a + r;

11.5 Práticas Diversas

11.5.1 Parênteses

Geralmente uma boa idéia o uso de parênteses livremente em expressões que envolvam operadores misturados para que sejam evitados problemas de precedência de operadores. Mesmo se a precedência do operador parecer clara, considerar que pode não ser para todos não se pode assumir que todos os programadores tenham o mesmo nível de conhecimento e entendimento.

if (a == b && c == d)

if ((a == b) && (c == d)) // CORRETO!

// EVITAR!

11.5.2 Valores de Retorno

Tente fazer com que a estrutura do programa se encaixe na intenção. Por exemplo:

if (expressaoBoleana) { return TRUE;

}

else { return FALSE;

}

Deve ser escrito como:

return expressaoBoleana;

Da mesma forma que:

if (condicao) { return x;

}

return y;

Deve ser escrito como:

return (condição ? x : y);

11.5.3 Expressões antes de “?” no Operador Condicional

Se uma expressão contendo um operador binário aparecer antes do sinal de interrogação (?) no ternário (?: operador), ele deveria ser usado entre parênteses. Por exemplo:

(x

>=

0)

?

x

:

-x

11.5.4 Comentários Especiais

Use XXX em um comentário para marcar algo que, mesmo contendo erros, funcione. Use FIXME para marcar algo que contenha erro e não funcione.

12. Exemplo de Código

12.1 Exemplo de Código Fonte Java

O seguinte exemplo mostra como formatar um código fonte Java contendo uma única classe pública. Interfaces são formatadas de forma similar. Para maiores informações, veja o item ―4.1.3 Declarações de Classe e de Interface‖ e ―6.2 Comentários de Documentação‖.

/*

*

%W% %E% Firstname Lastname

*

*

Copyright (c) 1993-1996 Sun Microsystems, Inc. All Rights Reserved.

*

*

This software is the confidential and proprietary information of Sun

*

Microsystems, Inc. ("Confidential Information"). You shall not

*

disclose such Confidential Information and shall use it only in

*

accordance with the terms of the license agreement you entered into

*

with Sun.

*

*

SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF

*

THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED

*

TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A

*

PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR

*

ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR

*

DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.

*/ package java.blah; import java.blah.blahdy.BlahBlah;

/**

*

Class description goes here.

*

*

@version 1.10 04 Oct 1996

*

@author Firstname Lastname

*/

public class Blah extends SomeClass { /* A class implementation comment can go here. */ /** classVar1 documentation comment */ public static int classVar1; /**

* classVar2 documentation comment that happens to be

* more than one line long

*/ private static Object classVar2; /** instanceVar1 documentation comment */ public Object instanceVar1; /** instanceVar2 documentation comment */ protected int instanceVar2; /** instanceVar3 documentation comment */ private Object[] instanceVar3;

/**

*

method

Blah documentation comment

*/ public Blah() {

//

implementation

goes here

}

/**

*

method

doSomething documentation comment

*/ public void doSomething() {

}

/**

//

implementation

goes here

*

method

doSomethingElse documentation comment

*

@param someParam description

*/

public void doSomethingElse(Object someParam) {

}

}

//

implementation

goes here