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

#	Part of Class/Interface Declaration	Notas
1	Class/interface documentation comment (/*.../)	�
2	class or interface statement	�
3	Class/interface documentation comment (/*.../)	Este coment�rio deve conter todas as informaç�es da classe ou interface de forma ampla visando sua documentaç�o.
4	Class (static) variables	Primeiro as vari�veis de classe publics, em seguida, os protecteds, o n�vel de pacote, em seguida, (sem modificador de acesso), e ent�o as privates.
5	Instance variables	Idem item 4
6	Constructors	�
7	Methods	Aqui os m�todos devem ser agrupados pelo seu n�vel de funcionalidade.

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.

Nota: os exemplos para utilizaç�o em documentaç�o deve ter um menor comprimento de linha, geralmente n�o mais do que 70 caracteres.

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.

Identifier Type	Rules for Naming	Exemplos
Packages	O prefixo do nome do pacote deve ser �nico, deve sempre ser escrito em letras min�sculas todo-ASCII e deve ser um dos nomes de dom�nio de n�vel superior, atualmente com, edu, gov, mil, net, org, c�digos de duas letras identificando os pa�ses, tal como especificado na norma ISO 3166, 1981. Componentes subseq�entes do nome do pacote varia de acordo com uma organizaç�o pr�prias convenç�es de nomenclatura internos. Tais convenç�es podem especificar que certos componentes do nome do diret�rio haver divis�o, departamento, projeto, m�quina, ou nomes de login.	com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese
Classes	Os nomes de classe devem ser substantivos, em mai�sculas e min�sculas com a primeira letra de cada palavra interna em mai�scula. Tente manter seus nomes de classe simples e descritivo. Sempre evite palavras-ligadas , evite todas siglas e abreviaturas, seja sem�ntico.	class Raster; class ImageSprite;
Interfaces	Nomes de interfaces devem ser usadas com as primeiras letras em mai�sculas como nome de classes.	interface RasterDelegate; interface Storing;
Methods	M�todos devem ser verbos, com a letra min�scula em primeiro lugar, com a primeira letra de cada palavra interna em mai�scula.	run(); runFast(); getBackground();
Variables	Os nomes de vari�veis n�o deve começar com underscore _ ou sinal de d�lar $ personagens, mesmo que ambos n�o s�o permitidos. Os nomes de vari�veis devem ser curtos, mas significativo. A escolha de um nome vari�vel deve ser mnem�nico, isto �, concebidos para indicar ao observador casual a intenç�o da sua utilizaç�o. Um personagem nomes de vari�veis devem ser evitadas, exceto para tempor�rios "descart�veis" vari�veis. Os nomes comuns para vari�veis tempor�rias s�o i, j, k, m, n e para inteiros, c, d, e e para caracteres	int i; char c; float myWidth;
Constants	Os nomes de vari�veis declaradas constantes de classes e de constantes ANSI deve ser todo em letras mai�sculas com palavras separadas por sublinhados ("_").	static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1;

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.

Conven��es de C�digo Java

Neste artigo iremos abordar a importância de convenções adotadas pela Sun e hoje pela Oracle, quanto ao uso da manutenabilidade (capacidade/facilidade de prestar manutenção) nos códigos-fonte.

A quem se destina

Qual a raz�o de saber convenç�es de c�digo

Coment�rios

Package e Import Statements

Alinhamento do c�digo

Coment�rios

Declaraç�es

Classes e Interfaces

Convenç�o para nomes

Artigos relacionados