Convenções de Código Java

A quem se destina

Gerentes de TI, desenvolvedores, analistas de sistemas, documentadores, auditores e outros relacionados à organização de empresas de T.I

Qual a razão de saber convenções de código

Inúmeras razões, algumas delas:

• 80% do tempo programadores, deveriam estar focados em regras de negócio, entendimento, estudos e outros 20% programando, sendo que ainda faltaria tempo para melhora do código;
• Dificilmente um código será mantido "eternamente" pelo seu criador original;
• Códigos bem escritos, bem descritivos, bem anotados aumentam a produtividade, diminuem a quantidade de treinamentos, facilita a leitura e agrada visualmente;
• Se você vende seu código como produto, você deve ter certeza que ele é um produto bem testado, empacotado para ser entregue e que faz o que promete, entregando valor ao seu cliente;
• Convenções padronizam métodos de usabilidade com boas práticas baseado no conhecimento e experiência de um corpo especializado na área;

Para que as convenções funcionem corretamente no seu ambiente de trabalho é ideal que todos sigam as conformidades dos padrões. Todos, isso deve ser levado como uma regra.

Comentários

/*
 * Classname             (nome da classe Java)
 * 
 * Version information   (versionamento)
 *
 * Date                  (Data e Hora)
 * 
 * author                (autor(res) da criação)
 * Copyright notice      (informações do método, pra que serve, idéia principal
 */

Package e Import Statements

Primeiro os pacote e depois os imports em seguida

package java.awt;

import java.awt.peer.CanvasPeer;

Note que o primeiro, pacote é um componente único, escrito em minúsculas e claro que você poderá fazer o uso da *(todos) em casos específicos, mas o ideal é que seja único diminuindo assim a gama de bibliotecas necessárias para futuros Deploys (implantações). Atualmente com, edu, gov, mil, net, org, ou uso em inglês de duas letras que identificam os códigos de países, conforme especificado na norma ISO 3166, 1981.

Composição de uma classe e Interfaces

Alinhamento do código

Inicie com 4 espaços ou um tab. A construção exata do recuo (espaços vs tabs)é indeterminado. Tabs deve ser definido exatamente cada 8 espaços (não 4).

Evite linhas com mais de 80 caracteres, uma vez que em alguns terminais fica mais difícil de ler.

Quando uma expressão não couber em uma única linha, quebrá-lo de acordo com estes princípios gerais:

• Quebre após uma vírgula.
• Quebre antes de um operador.
• Prefira quebras de nível superior para diminuir o nível-breaks.
• Se as regras acima expostas levarem à um código confuso ou ao código que está esmagado contra a margem direita, apenas coloque 8 espaços em seu lugar.

Aqui estão alguns exemplos de quebra de chamadas de método:

someMethod(longExpression1, longExpression2, longExpression3, 
        longExpression4, longExpression5);
 
var = someMethod1(longExpression1,
                someMethod2(longExpression2,
                        longExpression3)); 

Exemplo com códigos usados em métodos aritméticos:

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

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

Exemplo de códigos alinhando métodos. o Primeiro de forma convencional e o segundo ele mudaria as segunda e terceira linhas para a extrema direita se utilizado recuo convencional, então em vez disso, recua apenas 8 espaços

//DON'T USE THIS INDENTATION
if ((condition1 && condition2)
    || (condition3 && condition4)
    ||!(condition5 && condition6)) { //BAD WRAPS
    doSomethingAboutIt();            //MAKE THIS LINE EASY TO MISS
} 

//USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
} 

//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

Exemplo de 3 formas aceitáveis de métodos ternários

alpha = (aLongBooleanExpression) ? beta : gamma;  

alpha = (aLongBooleanExpression) ? beta
    : gamma;  

alpha = (aLongBooleanExpression)
    ? beta 
    : gamma;  

Comentários

Programas em Java podem ter dois tipos de comentários: comentários de implementação do código e comentários de documentação. Observações de aplicação são os encontrados no mesmo modo C ++, que são delimitados por / * ... * /, e / /. Comentários de documentação (conhecido como "comentários doc") são Java-only, e são delimitados por / ** ... * /. Comentários de documentação podem ser extraídos para arquivos HTML usando a ferramenta javadoc.

Comentários de implementação significa comentar o código ,ou parte dele ,ou para comentários sobre uma aplicação particular, um método de uma classe por exemplo.

Comentários de documentação são destinadas a descrever a especificação do código, a partir de uma perspectiva de implementação livre para ser lido por desenvolvedores que não necessariamente possuem o código fonte em mãos.

Os comentários devem ser usados ​​para dar uma visão geral do código e fornecer informações adicionais que não está prontamente disponível no próprio código. Os comentários devem conter apenas informações relevantes para a leitura e compreensão do programa. Por exemplo, informações sobre como o pacote correspondente é construído ou em qual diretório ele reside não deve ser incluído como um comentário.

Discussão de decisões de projeto não triviais ou não óbvia é inapropriado, sempre evitar a duplicação de informação que está presente em (e claro) o código. Em geral, evite quaisquer comentários que possam sair do cronograma do código (quando usar datas, fixe-se somente a data de criação) como o código evolui.

Comentários nunca devem incluir caracteres especiais, nem deve ser usado em demasia, mas sempre com parcimônia.

Alguns exemplos de códigos com comentários:

Um comentário de bloco deve ser precedido por uma linha em branco para separá-la do resto do código.

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

Comentários de bloco podem começar com / * -, reconhecido pelo travessão (1) como o início de um bloco de comentário que não deve ser reformatado, ou seja é um alerta de que, quem o fez quer que mantenha nessa forma. Exemplo:

/*-
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */

Ainda temos os comentários simples, exemplo:

if (condition) {

    /* Handle the condition. */
    ...
}

Trailing Comments

Comentários muito curtos podem aparecer na mesma linha do código que está inserida, mas deve ser deslocado o suficiente para separá-los das declarações. Se mais de um breve comentário aparecer em um trecho de código, todos eles deverão ser recuados para a definição mesma guia, deixando sempre alinhados.

Exemplo:

if (a == 2) {
    return TRUE;            /* special case */
} else {
    return isPrime(a);      /* works only for odd a */
}

Comentários de fim de linha "//"

O delimitador / / como comentário pode comentar uma linha completa ou apenas parcial. Ele não deve ser utilizado em linhas consecutivas para comentários de texto, no entanto, pode ser utilizado em linhas consecutivas para comentando secções de código. Exemplos de todos os estilos:

if (foo > 1) {

    // Do a double-flip.
    ...
}
else {
    return false;          // Explain why here.
}
//if (bar > 1) {
//
//    // Do a triple-flip.
//    ...
//}
//else {
//    return false;
//}

Declarações

Uma declaração por linha é recomendado desde que o a menção ao código seja justificada por seu tipo e (ou) referência, em outras palavras:

int level; // indentation level
int size;  // size of table

é preferível que, seja:

int level, size;

Nunca coloque tipos diferentes numa mesma linha. Exemplo:

	int foo,  fooarray[]; //errado!

No exemplo abaixo foi usado um espaço entre o tipo e o variável identificada, outra forma aceitável é o uso de tabs.

int	level;	        // indentation level
int	size;	         // size of table
Object	currentEntry;	 // currently selected table entry

Classes e Interfaces

Classes Java e interfaces seguem algumas regras de formatação, veja:

• Sem espaço entre um método e o parênteses e o nome do método "(" início de lista de parâmetros;
• Abertura da chaves "{" aparece no fim da mesma linha que foi declarado o código ;
• Fechamento da chaves "}" começa uma linha alinhada no conjunto do método a qual foi criada, exceto quando há códigos em parte em branco(vazio) ou nulo }"devendo aparecer imediatamente depois de aberto com "{"
• Métodos são sempre separados por uma linha em branco.

class Sample extends Object {
    int ivar1;
    int ivar2;

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

    int emptyMethod() {}

    ...
}

Convenção para nomes

As convenções de nomenclatura tem como objetivo tornar os programas mais compreensíveis, tornando-os mais fáceis de ler. Eles podem também fornecer informações sobre a função do identificador, por exemplo, quer se trate de um pacote, constante, ou de classe que pode ser útil na compreensão do código.

Nessa área de boas práticas em documentação do código temos ainda um amplo estudo e normas à seguir para se implantar as boas práticas no seu ambiente de trabalho, aconselho acessar o link de documentação.