Convenções de Código

1 - Introdução

O presente artigo pretende ser a tradução para português das convenções de programação em Java definidas pela Sun Microsystems.

Algumas alterações foram feitas para tornar o texto mais breve, mas nenhuma das regras foi alterada, todas as regras aqui presentes são as regras recomendadas da linguagem, não sendo obrigatórias, são mesmo assim importantes para que se possa escrever e manter código com qualidade.

1.1 - Qual a Necessidade de Convenções de Código

As convenções de código são para os programadores por várias razões:

80% do ciclo de vida do custo do software é gasto em manutenção.
Dificilmente um software é mantido durante a toda a sua vida pelo autor ou autores originais.
As convenções melhoram a legibilidade do software, permitindo aos engenheiros compreender código novo melhor e mais depressa.
Se o código acompanhar o produto final, é necessário que esteja tão bem escrito e formatado como outro produto.

Para que as convenções funcionem, todo o programador que escreva software tem de as cumprir. Todo.

2 - Nomes de Ficheiros

Lista de sufixos mais comuns usados no nome de ficheiros.

Tabela com sufixos usados

Tipo de Ficheiro	Sufixo
código fonte Java	.java
bytecode Java	.class

A nomenclatura dos ficheiros deve seguir a nomenclatura das classes que contêm.

3 - Organização de Ficheiros

Um ficheiro é constituído por secções que devem estar separadas por linhas vazias, opcionalmente acompanhadas de um comentário que identifique cada secção. Ficheiros com mais de 2000 linhas são difíceis de manter e devem ser evitados.

Para um exemplo de um ficheiro bem formatado consulte a secção #11 - Exemplo de Código Fonte Java

3.1 - Ficheiros de Código Fonte Java

Cada ficheiro de código Java possui apenas uma classe ou interface pública. Quando classes e interfaces privadas são associadas a classes públicas, podem ser colocadas no mesmo ficheiro de código. A classe ou interface pública tem de ser a primeira a aparecer no ficheiro.

Os ficheiros de código Java possuem a seguinte ordenação:

Comentários de início(ver #3.1.1 - Comentários Iniciais)

Declarações de package e import; por exemplo:

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

Declarações de Classe e Interface (ver #3.1.3 - Declaração de Classe e Interface)

3.1.1 - Comentários Iniciais

Todos os ficheiros de código-fonte devem começar com um comentário estilo C, que contém o(s) programador(es), a data e a nota de copyright, bem como uma breve descrição do objectivo do programa. Por exemplo:

/*
 * Nome da classe
 *
 * Informação da versão
 *
 * Copyright nota de copyright
 */

Em alternativa ao comentário estilo C, é comum serem usados comentários Javadoc. Neste caso a única diferença é na forma como o comentário toma início, sendo criado com dois asteriscos em vez de apenas um, exemplo:

/**
 * (...)
 */

3.1.2 - Declarações de Package e de Import

A primeira linha de um ficheiro de código-fonte que não seja um comentário terá de ser a declaração do package da classe. Depois dessa, seguem-se as declarações de import. Por exemplo:

package java.awt;

import java.awt.peer.CanvasPeer;
import javax.*

3.1.3 - Declaração de Classe e Interface

A tabela seguinte descreve os constituintes de uma classe e a ordem pela qual devem aparecer. Consulte a secção #11 - Exemplo de Código Fonte Java para obter ver um exemplo mais completo.


	Parte da Declaração da Classe/Interface	Notas
1	Comentário de documentação de classe/interface (/.../*).	Ver #5.2 - Comentários de Documentação para obter informação sobre o que deve ser incluído neste comentário.
2	Declaração de classe ou interface.
3	Comentário de implementação de classe/interface caso necessário (*/.../*)	Este comentário de conter qualquer informação referente à classe ou interface que não era apropriada para o comentário de documentação de classe/interface, ponto 1.
4	Variáveis de classe (static)	Primeiro variáveis públicas, depois protegidas e finalmente privadas.
5	Variáveis de instância	Primeiro variáveis públicas, depois protegidas e finalmente privadas.
6	Construtores.
7	Métodos.	Estes métodos devem ser agrupados por função em vez de visibilidade. Por exemplo, um método privado da classe pode aparecer entre dois métodos públicos de instância. O objectivo é facilitar a legibilidade e ajudar na compreensão do código.

4 - Indentação

A unidade de indentação a usar deverá ser de quatro espaços. A construção exacta da indentação, isto é, o uso de espaços ou tabs não é especificado, ficando à descrição do programador. Tabs devem estar definidas para exactamente 8 espaços (não 4).

4.1 - Comprimento das Linhas

Evite linhas com mais de 80 caracteres uma vez que podem não ser bem geridas por terminais e outras ferramentas. Nota: Exemplos colocados em documentação devem ter um tamanho menor, na generalidade não mais de 70 caracteres.

4.2 - Quebras de Linha

Quando uma expressão não couber numa única linha, deve ser quebrada seguindo as regras gerais:

Dividir depois de uma vírgula.
Dividir antes de um operador.
Optar por quebras de nível superior sobre quebras de nível inferior.
Alinhar a nova linha no início da expressão, ao mesmo nível que a linha anterior.
Se a regra anterior provocar código confuso ou aninhado à margem direita, devem ser usados apenas 8 espaços de indentação como alternativa

Alguns exemplos da aplicação das regras a chamadas de métodos:

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

var = function1(longExpression1,
                function2(longExpression2,
                          longExpression3));

Seguem dois exemplos de como quebrar uma expressão aritmética. O primeiro exemplo ilustra a solução preferida, uma vez que a divisão ocorre fora dos parêntesis, que são de nível superior.

longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6; // PREFERIDA

longName1 = longName2 * (longName3 + longName4
                        - longName5) + 4 * longname6; // EVITAR

Seguem dois exemplos de indentação de declarações de métodos. O primeiro exemplo apresenta o caso convencional, o seguindo exemplo iria mover a 3ª e 4ª linha para a direita se usasse a indentação convencional, por isso usa 8 espaços como alternativa.

//INDENTAÇÃO CONVENCIONAL
umMetodo(int arg1, Object arg2, String eMaisUmArgumento,
         Object eAindaOutro) {
    ...
}

//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized nomeExtremamenteLongoParaMetodo(int arg1,
        Object outroArg, String aindaOutroMetodo,
        Object eMaisOutro) {
    ... 
}

Quebras de linhas para blocos if devem ser feitas com a regra de 8 espaços uma vez que a divisão convencional de 4 espaços, diminui a visibilidade do corpo do bloco. Por exemplo:

//NÃO USE ESTA INDENTAÇÃO
if ((condição1 && condição2)
    || (condição3 && condição4)
    ||!(condição5 && condição6)) { //MÁS QUEBRAS
    fazerQualquerCoisa();          //TORNA ESTA LINHA FÁCIL DE PERDER
}

//USE ESTA INDENTAÇÃO COMO ALTERNATIVA
if ((condição1 && condição2)
        || (condição3 && condição4)
        ||!(condição5 && condição6)) {
    doSomethingAboutIt();
}

//OU USE ESTA
if ((condição1 && condição2) || (condição3 && condição4)
        ||!(condição5 && condição6)) {
    fazerQualquerCoisa();
}

Alguns exemplos de formas aceitáveis de formatar expressões com operadores ternários:

alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;

alpha = (aLongBooleanExpression)
        ? beta
        : gamma;

5 - Comentários

Programas em 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 comentários delimitados por /*...*/ e por //. Comentários de documentação são específicos de Java, e delimitados por /**...*/. Comentários de documentação podem ser extraídos para HTML usando a ferramenta javadoc, disponível com o JDK.

Comentários de implementação destinam-se a comentar o código ou pormenores de implementação. Comentários de documentação destinam-se a descrever a especificação do código, de uma perspectiva independente da implementação, para serem lidos por programadores, que poderão não ter acesso ao código-fonte.

Os comentários devem ser usados para fornecer visões geris e informações que não são facilmente obtidas através do código-fonte. Os comentários devem conter apenas informação que é relevante para a leitura e compreensão do programa. Por exemplo, a informação sobre como o package onde a classe se insere ou em que directoria se encontra não deve ser colocada nos comentários.

É apropriada a discussão de decisões que não são óbvias ou triviais, mas evite duplicar informação presente, de forma clara, no código. É fácil que os comentários repetidos fiquem desactualizados. Como regra geral, evite quaisquer comentários que seja provável tornarem-se desactualizados à medida que o código evolui. Nota: A quantidade de comentários reflecte muitas vezes a fraca qualidade do código. Se se sentir compelido a escrever um comentário sobre uma secção de código, pense em reescrever essa secção para a tornar mais clara.

Os comentários não devem ser envolvidos em grandes caixas criadas com asteriscos ou outros caracteres. Os comentários nunca devem incluir caracteres especiais como mudanças de linha (\n).

5.1 - Formatos de Comentários de Implementação

Os programas podem ter quatro estilos de comentários de implementação: bloco, única linha, no seguimento da linha, de fim de linha.

5.1.1 - Blocos de Comentários

Comentários de bloco são usados para fornecer descrição de ficheiros, métodos, estruturas de dados e algoritmos. Os comentários de bloco devem ser colocados no início de cada ficheiro e antes de cada método. Também podem ser usados noutros locais, tais como dentro de métodos. Comentários de bloco dentro de métodos e funções devem ser indentados ao mesmo nível que o código que descrevem.

Um comentário de bloco deve ser precedido por uma linha em branco para o distinguir do resto do código e possuir um asterisco no início de cada linha, excepto na primeira:

/*
 * Aqui está um comentário em bloco.
 */

Comentários de bloco podem ser iniciados com /*-, que é reconhecido pelo indent(1) como o início de um comentário de bloco que não deve ser reformatado. Exemplo:

/*-
 * Este é um comentário de bloco com uma formatação
 * especial que o indent(1) irá ignorar.
 *
 *     um
 *        dois
 *           três
 */

Nota: Se não usar o indent(1), não precisa usar /*-, ou sequer fazer qualquer alteração sob a suposição de que alguém possa executar o indent(1) no seu código.

Ver também #5.2 - Comentários de Documentação

5.1.2 - Comentários de Única Linha

Comentários curtos podem aparecer numa única linha indentados ao nível do código que os segue. Se um comentário não pode ser escrito numa única linha, deve seguir o formato de comentários em bloco (ver #5.1.1 - Blocos de Comentários). Um comentário de única linha deve ser precedido por uma linha em branco. Apresenta-se a seguir, um exemplo de comentários de uma linha (ver também #5.2 - Comentários de Documentação).

if (condição) {
    /* Tratar a condição. */
    ...
}

5.1.3 - Comentários no Seguimento da Linha

Comentários muito curtos podem aparecer na mesma linha do código que descrevem, mas devem ser colocados mais à direita para não se confundirem com as expressões de código. Se vários comentários curtos aparecerem num pedaço de código, devem ser alinhados pelo mesmo tab. Evite o estilo usado na linguagem Assembly, de colocar comentários no fim de todas as linhas de código executável.

Aqui está um exemplo de um comentário no seguimento de uma linha de código (ver também #5.2 - Comentários de Documentação):

if (a == 2) {
    return TRUE;                      /* caso especial */
} else {
    return ePrimo(a);                 /* funciona apenas em a ímpar */
}

5.1.4 - Comentários de Fim-De-Linha

O delimitador // inicia um comentário que termina no fim da linha, ao encontrar o terminador de fim de linha. Pode comentar uma linha completa ou apenas parte da linha. Não deve ser usado em linhas consecutivas para criar blocos de comentários; no entanto, podem ser usados em linhas consecutivas para comentar secções de código. Exemplo dos três estilos mencionados:

if (foo > 1) {
    // Fazer um duplo salto.
    ...
}
else
    return false;          // Explicar porquê aqui.

//if (bar > 1) {
//
//    // Fazer um triplo salto.
//    ...
//}
//else
//    return false;

5.2 - Comentários de Documentação

Nota: Ver #11 - Exemplo de Código Fonte Java para exemplos dos formatos de comentários descritos nesta secção. Para mais detalhes visite How to Write Doc Comments for Javadoc que inclui informação sobre marcadores de comentários de documentação (@return, @param, @see). Para mais informações sobre a ferramenta javadoc visite a página do javadoc.

Comentários de documentação descrevem as classes Java, as interfaces, construtores, métodos e atributos. Cada comentários é delimitado por /**...*/, com um comentário por API. Este comentário deve aparecer antes da declaração:

/**
 * A classe de exemplo oferece ...
 */
class Example { ...

Tenha em atenção que as classes e interfaces não são indentadas, enquanto que os seus membros são. A primeira linha de um comentário de documentação, (/**), para classes e interfaces não é indentada; linhas de comentários seguintes possuem uma indentação de um espaço (de forma a alinhar os asteriscos verticalmente). Membros, incluindo construtores, possuem uma indentação de 4 espaços para a primeira linha do comentário e 5 nas seguintes

Se precisa fornecer informação sobre uma classe, interface, variável ou método que não é apropriada para documentação, use um comentário em bloco (ver #5.1.1 - Blocos de Comentários) ou comentários de única linha (#5.1.2 - Comentários de Única Linha) imediatamente a seguir à declaração. Por exemplo, detalhes sobre a implementação da classe devem ir para um comentário em bloco, colocado imediatamente a seguir à declaração da classe, não na zona dos comentários de documentação da classe.

Comentários de documentação não devem ser colocados dentro dos blocos que definem os métodos ou os construtores uma vez que Java associa esses comentários com a primeira declaração que vem a seguir à sua posição. Isto pode provocar o aparecimento de documentação em situações erradas quando extraída para HTML.

6 - Declarações

6.1 - Número Por Linhas

É recomendado que seja feita apenas uma declaração por linha, uma vez que esta prática encoraja a criação de comentários. Por outras palavras:

int level; // nível de indentação
int size;  // tamanho da tabela

é preferível em detrimento de:

int level, size;

Em situação alguma devem as variáveis e funções ser declaradas na mesma linha, por exemplo:

long dbaddr, getDbaddr(); // ERRADO!

Não coloque tipos diferentes de dados na mesma linha:

int foo,      fooarray[]; //ERRADO!

Nota: Os exemplos acima assumem um espaço entre o tipo de dados e o identificador, uma alternativa aceitável é o uso de tabs, por exemplo:

int           level;              // nível de indentação
int           size;               // tamanho da tabela
Object        currentEntry;       // entrada da tabela seleccionada

6.2 - Posicionamento

Coloque declarações apenas no início dos blocos. (Um bloco é um pedaço de código delimitado por chavetas, { e }.)

Não espere pela primeira utilização para declarar variáveis; pode confundir programadores menos atentos e alterar a portabilidade do código dentro do seu âmbito.

void MyMethod() {
    int int1;                // início do bloco do método

    if (condition) {
        int int2;            // início do bloco do "if"
        ...
    }
}

Como regra que se prese possui uma excepção, a excepção à regra mencionada acima são os índices usados em ciclos for que em Java podem ser declarados na expressão do ciclo:

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

Evite declarações que escondem declarações de nível superior. Por exemplo, não use um nome já declarado dentro de um bloco interno:

int contador;
...
func() {
    if (condição) {
        int contador;           // EVITAR!!
        ...
    }
    ...
}

6.3 - Iniciação

Tente iniciar as variáveis locais na sua declaração. A única razão para não iniciar uma variável local onde a mesma é declarada é se o seu valor inicial depender da execução de um cálculo.

6.4 - Declaração de Classes e Interfaces

Ao criar classes e interfaces Java, as seguintes regras de formatação devem ser seguidas:

Não existe espaço entre o nome de um método e o parêntesis inicial, (, da sua lista de parâmetros;
A chaveta de abertura, {, aparece no fim da mesma linha que a expressão de declaração;
A chaveta de fecho } aparece sozinha, numa linha própria, indentada para corresponder à expressão de abertura. Excepção a esta regra é quando o bloco de código se apresenta vazia, em que a chaveta de fecho deve aparecer imediatamente após a chaveta de abertura; Exemplo:
```
class Sample extends Object {
    int ivar1;
    int ivar2;

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

    int emptyMethod() {}

    ...
}
```
Os métodos são separados por linhas em branco.

7 - Blocos e Linhas de Código

7.1 - Linhas Simples

Cada linha deve conter no máximo uma expressão. Exemplo:

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

Não use a vírgula como separador de múltiplas expressões a não ser por uma razão óbvia. Exemplo:

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

7.2. Expressões Compostas

Expressões compostas são expressões que contêm listas de expressões delimitadas por chavetas, { expressões }. Veja os exemplos nas secções seguintes.

As expressões contidas dentro das chavetas devem estar indentadas um nível a mais que expressão composta.
A chaveta de abertura deve estar ao fim da linha que inicia a expressão composta e a chaveta de fecho deve estar no início de uma linha, indentada ao mesmo nível que o início da expressão composta.
Chavetas são usadas em torno de todas as expressões, mesmo que seja apenas uma linha, quando fazem parte de uma estrutura de controlo, tal como if-else. Isto facilita a adição de expressões sem introduzir erros de programação devido a chavetas esquecidas.

7.3 - Linhas return

Uma linha que devolva um valor não deve usar parêntesis a não ser que os mesmos tornem o valor retornado mais evidente. Exemplos:

return;

return myDisk.size();

return (size ? size : defaultSize);

7.4 - Blocos if, if-else, if-else-if-else

O grupo de expressões if-else deve seguir a forma:

if (condição) {
    expressões;
}

if (condição) {
    expressões;
} else {
    expressões;
}

if (condição) {
    expressões;
} else if (condição) {
    expressões;
} else if (condição) {
    expressões;
}

Nota: expressões if devem usar sempre chavetas ({}). Evite a seguinte construção, propícia a erros:

if (condição) //A EVITAR! ESTA CONSTRUÇÃO OMITE AS CHAVETAS {}!
    expressão;

7.5 - Blocos for

Uma expressão for deve seguir a forma:

for (iniciação; condição; actualização) {
    expressão;
}

Uma expressão for vazia (expressão onde todo o trabalho é feito nas clausulas de iniciação, condição e actualização) deve seguir a forma:

for (iniciação; condição; actualização);

Ao usar a vírgula na cláusula de iniciação ou de actualização para uma expressão, evite a complexidade de usar mais que três variáveis. Se precisar, separe as expressos antes o ciclo for (no caso da iniciação) ou no fim do ciclo (no caso da actualização).

7.6. Blocos while

Uma expressão while deve possuir a seguinte forma:

while (condição) {
    expressões;
}

Uma expressão while vazia segue a forma:

while (condição);

7.7 - Blocos do-while

Uma expressão do-while deve seguir a forma:

do {
    expressões;
} while (condição);

7.8 - Blocos switch

Um bloco switch é formatado do seguinte modo:

switch (condition) {
    case ABC:
        expressões;
       /* continua */
    case DEF:
        expressões;
        break;
   case XYZ:
       expressões;
       break;
   default:
       expressões;
       break;
}

Sempre que um bloco case continue para o(s) bloco(s) abaixo, isto é, não inclui uma instrução break, adicione um comentário onde a instrução break estaria normalmente. Este uso é mostrado no exemplo anterior. Todos os blocos switch devem incluir uma secção default. A instrução break na secção default é redundante, mas evita erros de continuidade se outras secções case forem adicionadas. O seu uso é opcional.

7.9 - Blocos try-catch

Um bloco try-catch deve ter o seguinte formato:

try {
    expressões;
} catch (ClasseDeExcepção e) {
    expressões;
}

8. Espaços

8.1. Linhas em Branco

Linhas em branco melhoram a legibilidade por definirem secções de código que ficam relacionadas logicamente. Duas linhas em branco devem ser usadas nas seguintes circunstâncias:

Entre secções de ficheiros de código.
Entre definições de classes e interfaces. Uma linha em branco deve ser sempre usada quando:
- Servir para dividir métodos;
- Entre as variáveis locais de um método e a sua primeira expressão;
- Antes de um bloco de comentário (ver #5.1.1 - Blocos de Comentários) ou de única linha (ver #5.1.2 - Comentários de Única Linha);
Dividir secções lógicas dentro de um método para melhorar a leitura.

8.2. Espaços em Branco

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

Uma palavra reservada seguida de um parêntesis deve ser separada por um espaço. Exemplo:

while (true) {
    ...
}

Note que um espaço não deve ser usado entre o nome do método e o parêntesis de abertura. Isto ajuda a distinguir entre métodos e palavras reservadas em chamadas de métodos. - Um espaço deve aparecer depois de uma vírgula que separa uma lista de argumentos. - Todos os operadores binários, excepto o ., devem ser separados dos seus operandos por um espaço. Espaços em branco nunca devem separar operadores unitários, como menos unitário, incremento (++) e decremento ("--"). Exemplo:

a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
    n++;
}
println("size is " + foo + "n");

- As expressões num ciclo for devem ser separadas por espaços. Exemplo:

for (expr1; expr2; expr3)

- Casts devem ser seguidos de um espaço. Exemplos:

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

9 - Convenções de Nomenclatura

Convenções de nomenclatura tornam os programas mais fáceis de entender. Podem também dar informação sobre a função do identificador, por exemplo, se é uma constante, um package ou classe, o que pode ser útil na percepção do código.

Tipo de Identificador	Regras de Nomenclatura	Exemplos
Classes	Nomes das classes devem ser substantivos, escritos numa mistura de minúsculas e maiúsculas, onde a primeira letra é maiúscula, com a primeira letra de cada palavra interna em maiúscula. Tente manter os nomes das classes simples e descritivos. Use palavras completas, evite acrónimos ou abreviaturas ( a não ser que a abreviatura seja mais conhecida que o termo longo, como HTML ou URL).	class Raster; class ImageSprite;
Interfaces	Os nomes de interfaces devem seguir as mesmas regras das classes. Note que não é necessária qualquer distinção das interfaces através do uso da letra "I" no início do nome da interface.	interface RasterDelegate; interface Storing;
Métodos	Nomes de métodos devem ser verbos, escritos numa mistura de minúsculas e maiúsculas, onde a primeira letra é minúscula, com a primeira letra de cada palavra interna em maiúscula.	run(); runFast(); getBackground();
Variáveis	Todas as variáveis devem ser escritas usando uma mistura de minúsculas e maiúsculas, com a primeira letra em minúscula e a primeira letra das palavras internas em maiúsculas. Nomes de variáveis devem ser pequenos mas com significado. A escolha do nome de uma variável deve ser mnemónico, isto é, escolhido para indicar ao observador casual o seu objectivo. Variáveis com nomes compostos apenas por um caracter devem ser evitados, excepto no uso de variáveis temporárias e "descartáveis". Os nomes mais comuns para variáveis temporárias saão i, j, k, m, e n, quando estamos a trabalhar com inteiros; e c, d, e e para caracteres.	int i; char c; float minhaAltura;
Constantes	Os nomes de constantes devem ser todos em maiúsculas, com as palavras que os compõem separadas por underscore ("_").	int MIN_WIDTH = 4; int MAX_WIDTH = 999; int GET_THE_CPU = 1;

10 - Práticas de Programação

10.1 - Fornecer Acesso a Variáveis de Instância e de Classe

Não torne pública qualquer variável de classe ou de instância sem uma excelente razão. Frequentemente, as variáveis de instância não precisam ser acedidas explicitamente, sendo os acessos o resultado de uma invocação de um método.

Um exemplo de uma variável de instância pública é o caso de a classe ser, essencialmente, uma estrutura de dados, sem qualquer comportamento. Por outras palavras, se precisar de usar uma estrutura de dados como as de C, se isso fosse suportado por Java, então é aceitável que as variáveis sejam públicas sem a necessidade de métodos de acesso.

10.2 - Invocar Variáveis e Métodos de Classe

Evita usar um objecto para aceder a um método ou variável de classe (static), em alternativa use a classe correspondente. Exemplo:

classMethod();                        //OK
AClass.classMethod();                 //OK
anObject.classMethod();               //EVITAR!

10.3 - Constantes

Constantes numéricas não devem aparecer directamente no código, excepto para os valores -1, 0 e 1 que podem ser usados directamente num ciclo for como valores dos contadores.

10.4 - Atribuição das Variáveis

Evite atribuições de várias variáveis no mesma expressão. São mais difíceis de ler. Exemplo:

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

Não use o operador de atribuição num local onde pode ser facilmente confundido com um operador de igualadade. Exemplo:

if (c++ = d++) {                  // EVITAR! Em Java não é permitido
    ...
}

<code>

O código acima deve ser escrito da seguinte forma:

<code java5>
if ((c++ = d++) != 0) {
    ...
}

Não use atribuições embebidas no sentido de melhorar a performance da aplicação, esse é o trabalho do compilador, além de que raramente resulta na forma pretendida. Exemplo:

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

O código acima deve ser escrito como:

a = b + c;
d = a + r;

10.5 - Práticas Várias

10.5.1 - Parêntesis

Regra geral é uma boa ideia usar parênteses de forma livre por entre as expressões que envolvem misturas de operadores, evitando deste modo problemas com a precedência dos operadores. Mesmo que a precedência parece clara, pode ajudar outros para quem a precedência dos operadores não seja tão óbvia.

if (a == b && c == d)               // EVITAR!
if ((a == b) && (c == d))           // CORRECTO

10.5.2 Valores de Retorno

Tente fazer com que a estrutura do seu programa corresponda à intenção. Por exemplo, o código:

if (expressãoBoolean) {
    return TRUE;
} else {
    return FALSE;
}

deve ser escrito da seguinte forma:

    return expressãoBoolean;

Da mesma forma:

if (condição) {
    return x;
}
return y;

deve ser escrito como:

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

Expressões antes de '?' no Operador Condicionar

Se uma expressão contém um operador binário antes do ponto de interrogação de um operador ternário, o operador binário deve aparecer dentro de parêntesis. Por exemplo:

(x >= 0) ? x : -x

Comentários Especiais

Use XXX em comentários para sinalizar algo que funciona, mas que tem problemas. Use FIXME para sinalizar algo com erros e que não funciona.

11 - Exemplo de Código Fonte Java

O exemplo seguinte mostra como formatar uma ficheiro de código-fonte Java contendo apenas uma classe pública. A formatação das interfaces é similar.

/*
 * %W% %E% Primeiro Nome Último Nome
 *
 * 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;
/**
 * Colocar aqui a descrição da classe.
 *
 * @version    1.10 04 Oct 1996
 * @author     Primeiro Nome Último Nome
 */
public Classe Blah extends OutraClasse {
    /* Comentário da implementação da classe. */

    /** varDeClasse1 comentário de documentação */
    static public int varDeClasse1;

    /**
     * varDeClasse2 comentário de documentação que 
     * ocupa mais de uma linha
     */
    static private Object varDeClasse2;

    /** varDeInstancia1 comentário de documentação */
    public Object varDeInstancia1;

    /** varDeInstancia2 comentário de documentação */
    protected int varDeInstancia2;

    /** varDeInstancia3 comentário de documentação */
    private Object[] varDeInstancia3;

    /**
     * ...comentário de documentação do método Blah...
     */
    public Blah() {
        // ...segue a implementação...
    }

    /**
     * ...comentário de documentação do método fazerQualquerCoisa...
     */
    public void fazerQualquerCoisa() {
        // ...segue a implementação...

    }

    /**
     * ...comentário de documentação do método fazerQualquerCoisa...
     * @param umParametro descrição
     */
    public void fazerOutraCoisaQualquer(Object umParametro) {
        // ...segue a implementação...
    }
}

12 - Ver Também

As convenções originais e uma possível actualização, podem ser consultadas na página dedicada.

13 - Copyright

Baseado no documento "Java Code Conventions" datado de 12 de Setembro de 1997 pela Sun Microsystems, Inc. Não é intenção qualquer tentativa de obter crédito pelo texto original e todos os direitos são propriedade da Sun Microsystems. Foi feita uma tradução e adaptação livre do documento original, onde alguns pontos específicos do funcionamento interno da empresa Sun Microsystems foram removidos, no entanto, nenhuma das regras foi alterada.