Convenes para Codificao Java

Traduo: Jefferson Araujo

Bibliografia: Oracle Sun Microsystems




















ndice

1. INTRODUO ............................................................................................................ 4
1.1 POR QUE UTILIZAR CONVENO DE CDIGO?................................................................. 4
1.2 POR QUE UTILIZAR CONVENO DE CDIGO?................................................................. 4
2. NOMES DE ARQUIVOS ............................................................................................ 5
2.1 ARQUIVOS DE SUFIXOS .................................................................................................. 5
2.2 NOMES DE ARQUIVOS COMUNS ..................................................................................... 5
3. ORGANIZAO DE ARQUIVOS ............................................................................ 5
4. ARQUIVOS-FONTE JAVA ........................................................................................ 6
4.1 COMENTRIOS INICIAIS ................................................................................................. 6
4.2 DECLARAES DE PACOTES E IMPORTAES ................................................................ 6
4.3 DECLARAES DE CLASSE E DE INTERFACE .................................................................. 7
5. INDENTAO ............................................................................................................. 8
5.1 COMPRIMENTO DA LINHA .............................................................................................. 8
5.2 EMPACOTANDO LINHAS ................................................................................................. 8
6. COMENTRIOS ....................................................................................................... 10
6.1 FORMATOS DE COMENTRIOS DE IMPLEMENTAO .................................................... 10
6.1.1 COMENTRIOS DE BLOCO ......................................................................................... 11
6.1.2 COMENTRIOS DE LINHA-NICA .............................................................................. 11
6.1.3 COMENTRIOS DE TRILHA ........................................................................................ 12
6.1.4 COMENTRIOS DE FINAL DE LINHA .......................................................................... 12
6.2 COMENTRIOS DE DOCUMENTAO ............................................................................ 12
7. DECLARAES ....................................................................................................... 14
7.1 NMERO POR LINHA .................................................................................................... 14
7.2 LOCALIZAO ............................................................................................................. 14
7.3 INICIALIZAO ............................................................................................................ 15
7.4 DECLARAES DE CLASSE E INTERFACE ..................................................................... 15
8. DECLARAES / 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. ESPAO EM BRANCO ............................................................................................ 19
9.1 LINHAS EM BRANCO .................................................................................................... 19
9.2 ESPAOS EM BRANCO .................................................................................................. 20
10. CONVENES DE NOMENCLATURA ........................................................... 21
11. PRTICAS DE PROGRAMAO ..................................................................... 23
11.1 FORNECENDO ACESSO INSTNCIA E VARIVEIS DE CLASSE................................... 23
11.2 REFERINDO-SE A VARIVEIS DE CLASSE E MTODOS ................................................ 23
11.3 CONSTANTES ............................................................................................................. 23
11.4 ATRIBUIES DE VARIVEIS ..................................................................................... 23
11.5 PRTICAS DIVERSAS .................................................................................................. 24
11.5.1 PARNTESES ........................................................................................................... 24
11.5.2 VALORES DE RETORNO ........................................................................................... 24
11.5.3 EXPRESSES ANTES DE ? NO OPERADOR CONDICIONAL ...................................... 25
11.5.4 COMENTRIOS ESPECIAIS ....................................................................................... 25
12. EXEMPLO DE CDIGO ...................................................................................... 25
12.1 EXEMPLO DE CDIGO FONTE JAVA ............................................................................ 25




























1. Introduo

As convenes de cdigo so uma boa prtica de programao. Ajudam por exemplo na
manuteno de um sistema. A violao dessas regras prejudica e muito o
entendimento de uma API, por exemplo. Alm do mais, com as convenes, podemos
produzir um cdigo legvel e limpo, que demonstra qualidade de maneira
profissional.

1.1 Por que utilizar conveno de cdigo?

As convenes de cdigo so importantes para os programadores por uma
srie de razes:

80 % do tempo gasto com o software vai para a manuteno;
Dificilmente um software mantido por toda sua existncia pelo autor
original;
As convenes de cdigo melhoram a legibilidade do software, fazendo
com que engenheiros entendam o novo cdigo mais rapidamente e por
completo;
Se um cdigo 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 convenes funcionem, todas
as pessoas que escrevem software devem estar de acordo com as
convenes, este um processo que precisa ser divulgado desde a raiz para
que TODOS tenham em mente estas boas prticas.

1.2 Por que utilizar conveno de cdigo?

Esse documento reflete o padro do cdigo da linguagem JAVA apresentado
no JAVA Language Specification, da Sun Microsytems (atual Oracle). As
maiores contribuies so de Peter King, Patrick Naughton, Mike DeMoney,
Jonni Kannerva, Kathy Walrath e Scott Hommel.

Comentrios devem ser enviados atravs de formulrio para:
http://java.sun.com/docs/forms/sendusmail.html





2. Nomes de Arquivos

Essa seo lista os sufixos e nomes usados com maior freqncia.

2.1 Arquivos de Sufixos

O Software Java utiliza os seguintes sufixos:

Tipo de Arquivo Sufixo
Fonte Java .java
Cdigo de Byte Java .class

2.2 Nomes de Arquivos Comuns


Nome do Arquivo Uso
GNUmakefile
O nome preferido para criao de
arquivos.
Usa-se GNUmake para construo do
software.
README
Nome preferido do arquivo que resume
o contedo de um diretrio particular


3. Organizao de Arquivos

Um arquivo consiste de sees que devem ser separadas por linhas em branco e um
comentrio opcional identificando cada seo.
Arquivos com mais de 2000 linhas so 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 contm uma nica classe pblica ou de interface. Quando
classes privadas e interfaces so associadas a uma classe pblica, elas podem ser
colocadas no mesmo arquivo-fonte da classe pblica. A classe pblica deve ser a
primeira classe ou interface no arquivo.

Arquivos-fonte Java seguem a seguinte ordem:

Comentrios Iniciais (ver item 4.1);
Declaraes de pacotes e importes; por exemplo:

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

Declaraes de classe e de interface (ver item 4.3).

4.1 Comentrios Iniciais

Todos os arquivos-fonte devem comear com um comentrio c-style que
lista: nome da classe, verso, data, breve descrio do propsito do programa
e direitos autorais. Por exemplo:

/*
* Nome da Classe:
*
* Informao da Verso:
*
* Data:
*
* Propsito do Programa:
*
* Direitos Autorais:
*/

4.2 Declaraes de Pacotes e Importaes

A primeira linha sem comentrios da maioria dos arquivos-fonte Java uma
declarao de pacote. Aps isso, podem ser realizadas as declaraes de
importao. Por exemplo:

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

4.3 Declaraes de Classe e de Interface

A quadro a seguir descreve as partes de uma declarao de classe ou de
interface, na ordem em que elas devem aparecer. Ver o exemplo do item 12.1 que inclui
comentrios.



Declarao de parte da
Classe / Interface
Notas
1
Comentrios de
documentao de classe
/ interface (/**...*/)
Ver item 6.2 Comentrios de
Documentao para informao
do que deve conter este comentrio.
2
Declarao de classe ou
de interface

3
Comentrio de
implementao de classe
/ interface (/**...*/), se
necessrio
Esse comentrio deve conter
qualquer informao a respeito da
classe ou da interface no definida
no comentrio de documentao de
classe ou interface.
4
Variveis de classe
(esttica)
Primeiro as variveis de classes
pblicas, depois as protegidas, aps
isso, o nvel de empacotamento
(sem modificao de acesso) e, a
sim, a classe privada.
5 Variveis instanciveis
Primeiro as pblicas, depois as
protegidas e ento as privadas.
6 Construtores
7 Mtodos
Esses mtodos devem ser
agrupados por funcionalidade antes
do que por escopo ou
acessibilidade. Por exemplo, um
mtodo da classe privada pode
estar entre dois mtodos pblicos.
O objetivo fazer com que a leitura
e entendimento do cdigo seja
realizado mais facilmente.





5. Indentao

Quatro espaos devem ser usados como unidade de indentao. A construo exata de
indentao (espaos versus tabulaes) no especificada. Tabulaes devem ser
estabelecidas com 8 espaos (e no com 4).

5.1 Comprimento da Linha

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

Obs.: Exemplos para uso em documentao deve ter menor comprimento de
linha geralmente no mais que 70 caracteres.

5.2 Empacotando Linhas

Quando uma expresso no contiver uma nica linha, a sua quebra deve
ocorrer de acordo com alguns princpios:

A quebra deve ocorrer aps uma vrgula;
A quebra deve ocorrer antes de um operador;
Dar preferncia as quebras em nveis mais altos do que as de nveis mais
baixos;
Alinhar a nova linha com o comeo da expresso no mesmo nvel da
linha anterior;
Caso as regras acima venham a confundir o cdigo ou esprem-lo contra
a margem direita, apenas utilize a indentao de 8 espaos.

Aqui esto alguns exemplos de chamadas a mtodos com linhas quebradas:

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

variavel = funcao1(longExpression1,
funcao2(longExpression2,
longExpression3));

A seguir esto dois exemplos de quebra de uma expresso aritmtica. A
primeira a preferida, desde que a quebra ocorra fora da expresso contida
entre parnteses, que de um nvel elevado:

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

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

A seguir dois exemplos de mtodos de indentao de declaraes. O
primeiro o caso convencional. O segundo mudaria a 2 e a 3 linhas para a
direita se for usada a indentao convencional. Ao invs disto identar apenas
8 espaos:

//INDENTAO CONVENCIONAL
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}

//INDENTAR 8 ESPAOS PARA EVITAR IDENTAES MUITO DISTANTES
private static synchronized horkingLongMethodName (int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}

Empacotamento de linhas para declaraes "IF" devem geralmente usar a
regra de 8 espaos, uma vez que a regra convencional (4 espaos) dificulta a
visualizao. Por exemplo:

//NO USAR ESTA INDENTAO
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //PESSIMO EMPACOTAMENTO
doSomethingAboutIt(); //FACILITA PERDER A LINHA
}

//USAR ESTA INDENTAO
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}

//OU USAR ESTA INDENTAO
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}

Aqui esto trs formas aceitveis de formatar expresses ternrias:

alpha = (aLongBooleanExpression) ? beta : gama;

alpha = (aLongBooleanExpression) ? beta
: gama;
alpha = (aLongBooleanExpression)
? beta
: gama;








6. Comentrios

Os programas Java podem ter dois tipos de comentrios: comentrios de implementao
e comentrios de documentao. Comentrios de implementao so aqueles
encontrados em C++, delimitados por /*...*/, ou //. Comentrios de documentao
(tambm conhecidos como "doc comments") servem apenas para o Java e so
delimitados por /**...*/. Comentrios de documentao podem ser extrados para
HTML utilizando a ferramenta javadoc.

Comentrios de implementao so recursos para comentrios a respeito do cdigo ou
de uma implementao particular. Comentrios de documentao so usados para
descrever a especificao do cdigo, de uma perspectiva de livre implementao, a ser
lida por desenvolvedores que no tm necessariamente que ter o cdigo-fonte mo.

Comentrios devem ser usados para dar uma viso geral do cdigo e fornecer
informao adicional, que no facilmente disponvel no prprio cdigo. Comentrios
devem conter apenas informaes relevantes para ler e entender o programa. Por
exemplo, no devem ser includos como comentrios informaes sobre como o
empacotamento correspondente feito ou em qual diretrio ele se encontra.

Discusso sobre decises de design no triviais ou no bvias apropriada, mas evite a
duplicao de informao que est presente no cdigo. muito fcil comentrios
redundantes se desatualizarem. Em geral, evite alguns comentrios que provavelmente
se desatualizaro medida que o cdigo for se expandindo.

Obs: A freqncia de comentrios s vezes reflete a qualidade pobre do cdigo.
Quando o programador se sentir compelido a adicionar comentrios, dever ser
considerada a possibilidade de reescrever o cdigo para deix-lo mais claro.

Comentrios no devem ser fechados em grandes quadros desenhados com asteriscos
ou outros caracteres.
Comentrios nunca devem incluir caracteres especiais como caractere de alimentao
de formulrio ou retorno de espao.

6.1 Formatos de Comentrios de Implementao

Programas podem ter quatro estilos de comentrios de implementao: De
Bloco, Linha-nica, Em Trilha e Fim da Linha.




6.1.1 Comentrios de Bloco

Comentrios de bloco so usados para prover descries de arquivos,
mtodos, estruturas de dados e algoritmos. Comentrios de bloco devem ser
usados no incio de cada arquivo e antes de cada mtodo. Eles tambm
podem ser usados em outros lugares, como dentro de mtodos. Blocos de
comentrios dentro de uma funo ou mtodo devem ser identados no
mesmo nvel da descrio do cdigo. Um bloco de comentrio deve ser
precedido por uma linha em branco para determinar a separao do resto do
cdigo. Blocos de comentrios possuem um asterisco * no incio de cada
linha exceto na primeira. Por exemplo:

/*
* Aqui esta um Bloco de Comentrio.
*/

Blocos de comentrios podem iniciar com /*-, que reconhecido pelo
identador(1) como um incio de um bloco de comentrio que no deve ser
reformatado. Por exemplo:

/*-
* Este um bloco de comentrio com algumas formataes
* muito especiais que eu quero identador(1) ignore.
*
* um
* dois
* trs
*/

Obs: Se o identador(1) no for utilizado, no deve ser usada a combinao
/*- no cdigo nem devem ser feitas outras concesses, pois sempre h a
possibilidade de outro programador utiliz-lo em seu cdigo.

Ver tambm o item 6.2 Comentrios de Documentao.

6.1.2 Comentrios de Linha-nica

Pequenos comentrios podem aparecer em uma linha nica identados no
nvel do cdigo que segue. Se um comentrio no pode ser escrito em uma
linha nica, deve ser seguido o formato do comentrio em bloco (Ver item
6.1.1 Comentrios de Bloco). Um comentrio de linha nica devem ser
precedidos por uma linha em branco. Segue abaixo um exemplo de um
comentrio de linha nica utilizando codificao Java:

if (condition) {
/* Manipular a condio. */
...
}


6.1.3 Comentrios de Trilha

Pequenos comentrios podem aparecer na mesma linha em que o cdigo esta
sendo descrito, mas devem ser deslocados longe o suficiente para separ-los
das declaraes. Se mais de um pequeno comentrio aparecer em um pedao
de cdigo, todos eles devem ser identados com o mesmo parmetro de
tabulao.

Segue abaixo um exemplo de um comentrio de linha nica utilizando
codificao Java:

if (a == 2) {
return TRUE; /* caso especial */
} else {
return isprime(a); /* usa a condio a */
}


6.1.4 Comentrios de Final de Linha

O delimitador de comentrio // pode se referir a uma linha inteira ou pode
ser utilizado para continuao de uma linha anterior em uma nova linha (ou
seja, comentar parte de uma linha). No deve ser usado em mltiplas linhas
consecutivas para textos de comentrios; entretanto, pode ser usado em
mltiplas linhas consecutivas para comentar sees de cdigo. Segue abaixo
exemplos utilizando estes trs estilos utilizando a linguagem Java:

if (foo > 1) {
// Faa um duplo-flip.
...
} else {
return false; // Explicar o porque aqui.
}

//if (bar > 1) {
//
// // Faa um triplo-flip.
// ...
//}
//else
// return false;


6.2 Comentrios de Documentao

Obs: Ver o item 12.1 Exemplo de arquivo-fonte Java para exemplos
de formatos de comentrios descritos aqui.

Para maiores detalhes, ver How to Write Doc Comments for Javadoc que
inclui informao em tags de comentrios de documentao (@return,
@param, @see) no endereo abaixo:

http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

Para maiores detalhes sobre comentrios de documentao e javadoc, veja a
pgina do javadoc em:

http://java.sun.com/products/jdk/javadoc/

Comentrios de documentao descrevem classes Java, interfaces,
construtores, mtodos e campos. Cada comentrio de documentao
mantido dentro dos delimitadores de comentrio /**...*/, com um comentrio
por API (Classe, interface, construtor, mtodo ou campo). Esse comentrio
deve aparecer imediatamente antes da declarao. Por exemplo:

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

Perceba que classes e interfaces no esto identadas, enquanto seus membros
esto. A primeira linha do comentrio de documentao (/**) para classes e
interfaces no identada; cada linha de comentrio de documentao
subseqente possui um espao de indentao (para verticalmente se alinhar
aos asteriscos). Membros, incluindo construtores, possuem quatro espaos
para a primeira linha de comentrio de documentao e cinco espaos para
as demais.

Se for preciso dar informao sobre uma classe, interface, varivel ou
mtodo que no apropriado para documentao, deve ser utilizado um
comentrio de bloco (ver item 6.1.1) ou comentrio de linha-nica (ver item
6.1.2) imediatamente aps a declarao. Por exemplo, detalhes sobre a
implementao de uma classe devem ir em um tipo de comentrio de bloco
seguindo a declarao de classe e no no comentrio de documentao da
classe.

Comentrios de documentao no devem ser posicionados dentro de um
bloco de definio de mtodo ou de um construtor, porque Java associa
comentrios de documentao com a primeira declarao aps o comentrio.





7. Declaraes

7.1 Nmero por Linha

Uma declarao por linha recomendada desde que a mesma incentiva a
comentar. Em outras palavras,






prefervel:



De forma alguma variveis e funes devem ser declaradas na mesma linha.
Por exemplo:

long dbaddr, getDbaddr(); // ERRADO!

Tambm no podemos colocar diferentes tipos de dados na mesma linha. Por
exemplo:

int foo, fooarray[]; // ERRADO!

Obs: Os exemplos acima usam um espao entre o tipo do dado e o
identificador. Uma outra alternativa aceitvel a utilizao de tabulao. Por
exemplo:





7.2 Localizao

Coloque as declaraes apenas no incio dos blocos. (Um bloco qualquer
cdigo cercado por chaves { e }.) No espere para declarar variveis at
a sua primeira utilizao; isso pode confundir o programador descuidado e
prejudicar a portabilidade do cdigo dentro do escopo.
int nivel; // nvel de
indentao
int tamanho; // tamanho da tabela
int nivel, tamanho;
int nivel; // nvel de indentao
int tamanho; // tamanho da tabela
Object entradaAtual; // entrada atual da tabela selecionada








Uma exceo para esta regra refere-se aos ndices de loops do tipo for, nos
quais o Java pode ser declarado na declarao for:



Evite declaraes locais que ocultem declaraes no nos nveis superiores.
Por exemplo, no declare uma varivel com o mesmo nome em um bloco
interno:










7.3 Inicializao

Tente inicializar variveis locais onde elas so declaradas. A nica razo
para no inicializar uma varivel onde elas so declaradas se o valor inicial
da mesma depender de algum processamento que necessite ocorrer primeiro.

7.4 Declaraes de Classe e Interface

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

No colocar espaos entre o nome do mtodo e os parnteses (
comeando sua lista de parmetros;
Chave de abertura { deve aparecer no fim da mesma linha de comando
da declarao;
Chave de fechamento } deve comear a linha identada para coincidir
com a sua declarao de abertura correspondente, exceto quando uma
declarao nula a chave } deve aparecer imediatamente aps a chave
de abertura {;
void meuMetodo() {
int int1; // incio do bloco de mtodo

if (condicao) {
int int2; // incio do bloco de if
...
}
}
for (int i = 0; i < maxLoops; i++) { ...
int count;
...
func() {
if (condicao) {
int count; //EVITAR!
...
}
...
}

class Exemplo extends Object {
int ivar1;
int ivar2;

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

int metodoVazio() {}

...
}

Mtodos devem ser separados por uma linha em branco.
8. Declaraes / Comandos

8.1 Comandos Simples

Cada linha deve conter no mximo um comando. Por exemplo:


argv++; argc--; // EVITAR!
argv++; // CORRETO!
argc--; // CORRETO!

No use vrgula para agrupar mltiplos comandos a menos que seja por uma
razo obvia. Por exemplo:




8.2 Comandos Compostos

Comandos compostos so comandos que contm listas de comandos
encapsulados dentro de chaves { comandos }. Ver os exemplos a seguir:

Os comandos encapsulados entre chaves devem ser identados um nvel
acima do comando composto;
A chave de abertura deve estar no fim da linha que comea o comando
composto; a chave de fechamento } deve comear a linha e estar
identado no comeo do comando composto;
Chaves so utilizadas em volta de todos os comandos, mesmo comandos
simples, quando so parte de uma estrutura de controle, tanto quanto em
comandos if-else ou for. Isso torna mais fcil a adio de comandos
if (err) {
Format.print(System.out, error), exit(1); // ERRADO!
}
sem introduzir erros acidentalmente devido ao esquecimento da incluso
de chaves.

8.3 Comando de Retorno (return)

O comando return com um valor no deve usar parnteses 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:



8.5 Comandos for

Um comando for deve ter a seguinte forma:

for (inicializacao; condicao; atualizacao) {
comandos;
}

if (condicao) // EVITAR! ESTE TIPO OMITE AS CHAVES {}!
comando;
Um comando forvazio (um em que todo o trabalho feito nas clusulas de
inicializao, de condio ou de atualizao) deve ter a seguinte forma:

for (inicializacao; condicao; atualizacao);

Quando usado a vrgula nas clusulas de inicializao ou atualizao de um
comando for, evite a complexidade de utilizar mais de trs variveis. Se
preciso, utilize comandos separados antes do loop for (para clusula de
inicializao) ou no final do loop (para clusula de atualizao).

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:


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:

while (condicao);
switch(condicao) {
case ABC:
comandos;
/* fallsthrough */
case DEF:
comandos;
break;

case XYZ:
comandos;
break;

default:
comandos;
break;
}
Toda ocorrncia de um caso falls through (no incluir um comando
break), deve ter adicionado um comentrio onde o comando break
normalmente deveria estar. Isto mostrado no exemplo acima com o
comentrio /* falls through */.

Todo comando switch deve incluir um caso padro (default). O break no
caso padro redundante, mas previne a entrada em uma situao de erro se
posteriormente um novo caso for includo.


8.9 Comando try-catch

Um comando try-catch deve ter o seguinte formato:

try {
comandos;
} catch (ExceptionClass e) {
comandos;
}

9. Espao em Branco

9.1 Linhas em Branco

Linhas em branco melhoram a leitura pela separao de sees de cdigo
que esto logicamente relacionadas.

Duas linhas em branco devem sempre ser usadas nas seguintes
circunstncias:

Entre sees dos arquivos-fonte;
Entre definies de classes e interfaces.

Uma linha em branco deve sempre ser usada nas seguintes circunstncias:
Entre mtodos;
Entre variveis locais em um mtodo e seu primeiro comando;
Antes de um comentrio de bloco (ver item 6.1.1) ou de linha-nica (ver
item 6.1.2);
Entre sees lgicas dentro de um mtodo para melhorar a leitura e
entendimento.

9.2 Espaos em Branco
Espaos em branco devem ser usados nas seguintes circunstncias:

Uma palavra-chave (keyword) seguida por parnteses deve ser separada
por um espao. Por exemplo:

while (true) {
...
}
Note que um espao em branco no deve ser usado entre o nome do
mtodo e seu parnteses de abertura. Isso ajuda a distinguir palavras-
chave (keywords) de chamadas de mtodo.
Um espao em branco deve aparecer aps as vrgulas na lista de
argumentos;
Todos os operadores binrios (exceto .) devem ser separados de seus
operandos por espaos. Espaos em branco nunca devem separar
operadores nicos, como smbolo de subtrao simples (-), de
incremento (++) ou de decrscimo () 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 expresses em um comando for devem ser separadas por espaos
em branco. Por exemplo:

for (expr1; expr2; expr3)

Casts devem ser seguidos por um espao em branco. Por exemplo:

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

10. Convenes de Nomenclatura

Convenes de Nomenclatura faz com que os programas fiquem mais fceis de serem
lidos. Eles podem tambm dar informao sobre a funo ou o identificador por
exemplo, se uma constante, pacote ou classe que pode ser til no entendimento do
cdigo.
Tipo de
Identificador
Regras para Nomenclatura Exemplos
Classes Os nomes de classe devem ser
substantivos, uma combinao
de tamanhos de fonte (fontes
maisculos e minsculos) com
a primeira letra em maisculo
e as compostas tambm em
maisculo, as demais seguem
em minsculo. Os nomes de
classes devem, sempre que
possvel, ser simples e
descritivos. Usar palavras
completas evitando
acrnimos e abreviaes (a
menos que a abreviao seja a
forma mais usada e conhecida
do que a palavra longa, como
URL ou HTML)
class Imposto;
class PesquisaImposto;
Pacotes O prefixo de um pacote
sempre escrito em letras
minsculas em padro ASCII
e deve ser um dos nomes de
domnio de alto nvel
atualmente com, edu, gov,
mil, net, org ou um dos
cdigos de duas letras em
ingls que identifica os pases
de acordo com a especificao
ISO Standard 3166, 1981.
Componentes subseqentes do
nome do pacote variam de
acordo com a conveno
interna da prpria
organizao. Assim,
convenes devem especificar
que um certo nome de
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
diretrio de componente
diviso, departamento,
projeto, mquina ou login.
Interfaces Os nomes de interface devem
seguir o mesmo padro de
nomenclatura dos nomes das
classes.
interface ImpostoInterface;
interface VeiculoInterface;
Mtodos Os mtodos devem ser verbos,
com a primeira letra em
minscula e a primeira letra
das demais compostas em
letra maiscula.
run();
runFast();
getBackground():
Variveis Exceto para variveis, todas as
instncias, classes e classes
constantes se formam com a
primeira letra minscula. As
palavras compostas internas
devem iniciar com letra
maiscula.
Nomes de variveis devem ser
pequenos mas com um
significado. A escolha de um
nome de varivel deve ser
mnemnico ou seja,
desenhado para indicar a
inteno de seu uso. Os nomes
de variveis com apenas um
caractere devem ser evitados,
exceto nos casos de variveis
temporrias descartveis.
Os nomes mais usuais para
variveis temporrias so:
i,j,k,m e n para inteiros; c,d, e
e para caracteres.
int i;
char c;
float meuTamanho;
Constantes Os nomes de variveis
constantes de classes
declaradas e de constantes
ANSI devem ser totalmente
em letras maisculas com as
palavras separadas por
sublinhado (_). (As constantes
ANSI devem ser evitadas para
facilitar o debugging.).
static final int MIN_WIDTH = 4;
static final int MAX_WIDTH =
999;
static final int GET_THE_CPU =
1;

11. Prticas de Programao

11.1 Fornecendo Acesso Instncia e Variveis de Classe

No faa qualquer instncia ou varivel de classe publica sem ter uma boa
razo. Muitas vezes, variveis de instncia no precisam ser explicitamente
obtidas ou definidas muitas vezes o que acontece como um efeito colateral
de chamadas de mtodo.

Um exemplo de um apropriado uso de variveis de instncia pblicas o
caso quando a classe essencialmente uma estrutura de dados, sem
comportamento prprio. Em outras palavras, se tivesse usado struct ao invs
de uma class (se o Java suportasse struct), ento seria apropriado fazer
instncias de variveis pblicas de classe.

11.2 Referindo-se a Variveis de Classe e Mtodos

Evite usar um objeto para acessar uma varivel de classe (static) ou mtodo.
Use um nome de classe ao invs disso. Por exemplo:

classMethod(); //OK
AClass.classMethod(); //OK

AnObject.classMethod(); //EVITAR!

11.3 Constantes

Constantes numricas (literais) no 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 Atribuies de Variveis

Evite atribuir um valor para diversas variveis em uma nica instruo.
Dificulta sua leitura. Por exemplo:

fooBar.fChar = barFoo.lchar = c; // EVITAR!

No use operadores de atribuio em um lugar onde pode ser facilmente
confundido com um operador de igualdade. Por exemplo:

if (c++ = d++) { // EVITAR! Java no permite!
...
}

Deve ser escrito desta forma:




No use atribuies embutidas em uma tentativa de melhorar a performance
de execuo do cdigo. Isso tarefa do job de compilao, e alm disso, isso
na verdade raramente ajuda. Por exemplo:

d = (a = b + c) + r; // EVITAR!

Deve ser escrito da seguinte forma:




11.5 Prticas Diversas

11.5.1 Parnteses

Geralmente uma boa idia o uso de parnteses livremente em expresses que
envolvam operadores misturados para que sejam evitados problemas de
precedncia de operadores. Mesmo se a precedncia do operador parecer
clara, considerar que pode no ser para todos no se pode assumir que
todos os programadores tenham o mesmo nvel de conhecimento e
entendimento.




11.5.2 Valores de Retorno

Tente fazer com que a estrutura do programa se encaixe na inteno. Por
exemplo:







if ((c++ = d++) != 0) {
...
}
a = b + c;
d = a + r;
if (a == b && c == d) // EVITAR!
if ((a == b) && (c == d)) // CORRETO!

if (expressaoBoleana) {
return TRUE;
} else {
return FALSE;
}
Deve ser escrito como:



Da mesma forma que:

if (condicao) {
return x;
}
return y;

Deve ser escrito como:



11.5.3 Expresses antes de ? no Operador Condicional

Se uma expresso contendo um operador binrio aparecer antes do sinal de
interrogao (?) no ternrio (?: operador), ele deveria ser usado entre
parnteses. Por exemplo:

(x >= 0) ? x : -x

11.5.4 Comentrios Especiais

Use XXX em um comentrio para marcar algo que, mesmo contendo erros,
funcione. Use FIXME para marcar algo que contenha erro e no funcione.

12. Exemplo de Cdigo

12.1 Exemplo de Cdigo Fonte J ava

O seguinte exemplo mostra como formatar um cdigo fonte Java contendo
uma nica classe pblica. Interfaces so formatadas de forma similar. Para
maiores informaes, veja o item 4.1.3 Declaraes de Classe e de
Interface e 6.2 Comentrios de Documentao.

/*
* %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
return expressaoBoleana;
return (condio ? x : y);
* 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...
}
}