Deixando o seu cdigo bem formatado com o uso das convenes da Sun e Javadoc author: Jonas Mayer (jmayer13)

Nesse artigo sero apresentados as convenes Java adotadas pela Sun e o Javadoc ferramenta criada pela Sun para documentao e as convenes SQL. Tambm ser mostrado como configurar a IDE NetBeans para gerar seus prprios modelos de de classes. 1. CONVENES DE CDIGO JAVA Mas o que essa conveno? um padro para o desenvolvimento de cdigos Java. 1.1. Nomes de Arquivo 1.1.1. Extenso de Arquivos .java - Java source .class - Java bytecode 1.1.2. Organizao dos arquivos Um arquivo consiste de sees que devem ser separadas por linhas em branco e opcionalmente de um comentrio identificando cada seo. Evite arquivos de cdigo com mais de 20.000 linhas pois ficam pesados. 1.1.3. Arquivos de cdigo Java Cada arquivo de cdigo Java contem uma nica classe publica ou interface. Quando classes privadas e interfaces so associadas com uma classe publica, voc pode coloc-los no mesmo no mesmo arquivo de cdigo da classe publica. A classe pblica deve ser a primeira classe ou interface no arquivo. Arquivos de cdigo Java devem seguir a ordem: - Comentrio Inicial; - Declarao do Package e Imports; - Declarao de classes e interfaces; 1.1.3.1. Comentrio Inicial Todos os arquivos de cdigo deveriam iniciar com um comentrio estilo C (/*...*/) que lista o programador(es), a data, um aviso de direitos autorais (copyright notice) e tambm uma breve descrio do propsito do programa. Por Exemplo:
/* * Classname * * Version info * * Copyright notice */

1.1.3.2. Declarao de Package e Imports A primeira linha no comentada da maioria dos arquivos de cdigos Java a declarao do Package. Depois disso, seguido da declarao dos imports. Por exemplo: 1

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

1.1.3.3. Declarao de classes e interfaces A tabela a seguir descreve as partes de uma declarao de uma classe ou interface, na ordem em que ela deve aparecer. Parte da declarao Classe/Interface 1 2 3 Comentrio de documentao da classe/interface (/** ... */) Declarao da class ou interface Comentrios de implementao da classe/interface (/* ...*/), se necessrio Variveis de classe (static) Variveis de instancia Construtores Mtodos Estes mtodos devem ser agrupados por funcionalidade e no por escopo ou acessibilidade. Esse comentrio deve conter qualquer informao no apropriada para o comentrio da documentao da classe/interface. Primeiro as variveis de classe public, depois as protected, e depois as private. Primeiro public, depois protected, e depois private. Notes Documentrio Javadoc.

4 5 6 7

1.2. Indentao Devem ser usados quatro espaos como uma unidade de indentao. A exata constituio de uma indenizao no especificada (Tabs ou espaos). Tabs devem ser de exatamente 8 espaos (no 4). 1.2.1. Comprimento da Linha Evite linhas com mais de 80 caracteres, uma vez que elas no so bem manipuladas por terminais e algumas ferramentas. NOTA: Exemplos para uso em documentao devem ter linhas mais curtas - geralmente no mais que 70 caracteres. 1.2.2. Quebra de linhas Quando uma expresso no couber em uma nica linha, quebre-a com os seguintes princpios gerais: - Quebre depois da virgula. - Quebre antes do operador. - Prefira quebra de linha no nvel mais alto do que no nvel mais baixo. - Alinhe a nova linha com o mesmo nvel que o inicio da expresso da linha anterior. - Se as regras acima conduzirem a um cdigo confuso ou a um cdigo esmagado na margem direita, ento apenas indetente 8 espaos. Aqui esto alguns exemplos de quebra linha:

function(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = function1(longExpression1, function2(longExpression2, longExpression3));

A seguir temos dois exemplos de quebra de linha em expresses aritmticas. O primeiro o indicado, uma vez que a quebra ocorre fora dos parenteses da expresso, que esto no nvel superior.
longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // INDICADO longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; // EVITAR

A seguir temos dois exemplos de indentao de declarao de mtodos. O primeiro um caso convencional. O segundo passaria a segunda e terceira linha para a extremidade direita se fosse usada a indentao convencional, ento em vez disso indentado apenas 8 espaos.
//INDENTAO CONVENCIONAL someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } //INDENTAO DE 8 ESPAOS PRA EVITAR IDENTAO MUITO PROFUNDA private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... }

Quebra de linha para declarao if geralmente devem usar a regra de 8 espaos, uma vez que a convencional(4 espaos) torna com que o corpo difcil de ver.
//NO USE ESTA INDENTAO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //QUEBRA RUIM doSomethingAboutIt(); //DEIXA ESSA LINHA FCIL DE SE ENGANAR } //USE ESTA INDENTAO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } //OU USE ESTA if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); }

1.3. Comentrios Programas Java podem conter dois tipos de comentrios: Comentrios de implementao - aqueles encontrados em C, servem para comentar o cdigo ou uma implementao em particular. Podem ser delimitados por
/* * */

ou ainda
//

Comentrio de documentao - usados na documentao com o Javadoc. So definidos por

/** * */

Comentrios devem ser usados para dar uma viso geral do cdigo e prover informaes adicionais aquilo que no esta prontamente disponvel no prprio cdigo. Comentrios devem conter somente informaes relevantes para a leitura e compreenso do programa. 1.4. Declaraes 1.4.1. Numero por linha Uma declarao por linha recomendada visto desde que ela incentiva a comentar. Em outras palavras,
int level; //nvel de indetao int size; //tamanho da tabela

preferido em relao
int level, size;

Em hiptese nenhuma uma variveis e funes podem ser declaradas na mesma linha.
long dbaddr, getDbaddr(); //ERRADO!

No coloque tipos diferentes na mesma linha.

int foo, fooarray[]; //ERRADO!

NOTA: Os exemplos acima usam um espao entre o tipo e o identificador. Outra alternativa aceitvel usar tabs.

int level; int size; Object currentEntry;

//nvel de indentao //tamanho da tabela //clula da tabela selecionada atualmente

1.4.2. Localizao Somente coloque declaraes no comeo de blocos. No espere para declarar variveis quando elas forem usadas uma primeira vez.
void MyMethod() { int int1; // incio do bloco do mtodo if (condition) { int int2; // inicio do bloco "if" ... } }

1.4.3. Inicializao Tente inicializar variveis locais onde elas so declaradas. A nica razo para no inicializar uma varivel onde est esta declarada se o valor inicial depende de alguns clculos que ocorrem primeiro. 1.4.4. Declarao de Classes e Interfaces Quando escrevermos classes e interfaces Java, as seguintes regras devem ser seguidas : - Sem espao entre o nome do mtodo e o parenteses que inicia a sua lista de parmetros - Abrir colchetes "{" aparece no final da mesma linha que o comando de declarao. - Fecha colchetes "{" inicia em uma linha prpria recuando para combinar com a abertura de colchetes, da correspondente declarao, exceto quando a declarao nula neste caso o "}" deve seguir imediatamente depois do "}".
class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... }

- Mtodos devem ser separados por uma linha em branco. 1.5. Declaraes 1.5.1. Declaraes Simples Cada linha deve conter apenas uma declarao. Exemplo:
argv++ ; argv--; //EVITAR

No use virgula para agrupar varias instrues a menos que seja por uma razo bvia. Exemplo: 5

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

1.5.2. Declarao Complexas Declaraes compostas so declaraes que contem listas de instrues entre as chaves "{ Declaraes }". Veja as seguintes sees para exemplos. - As declaraes fechadas devem ser indentadas um nvel mais do que o comando composto; - A abertura de colchetes deve estar no final da linha que se inicia a expresso composta; o fechamento de colchetes deve comear uma linha e ser recuado para o incio da expresso composta; - Colchetes so usadas em torno todas as declaraes, at mesmo em declaraes individuais, quando elas fazem parte de uma estrutura de controle, como uma instruo if-else ou for. Isto torna mais fcil adicionar declaraes sem acidentalmente gerar erros, devido falta de colchetes. 1.5.3. Declarao return Uma declarao return com um valor no deve usar parenteses, a menos que eles faam o valor de retorno mais obvio de alguma forma ou claro, o retorno seja uma expresso. 1.5.4 Declarao if, if-else, if-else-if-else A classe de declarao if-else deve seguir a seguinte forma:
if (condio) { declarao; } if (condio) { declarao; } else { declarao; } if (condio) { declarao; } else if (condio) { declarao; } else if (condio) { declarao; }

NOTA: Sempre use colchetes {} em declaraes if . Evite a seguinte forma propensa a erro:
if (condio) //EVITE! ISTO OMITE OS COLCHETES{}! declarao;

1.5.5. Declarao for A declarao for deve seguir a seguinte forma:

for (inicializao; condio; update) { declarao; }

1.5.6. Declarao while Uma declarao while deve seguir a seguinte forma;
while (condio) { declarao; }

1.5.7. Declarao do-while Uma declarao do-while

do { declarao; } while (condio);

1.5.8. Declarao switch Uma declarao switch deve seguir a seguinte forma;
switch (condio) { case ABC: declarao; /* passa atravs */ case DEF: declarao; break; case XYZ: declarao; break; default: declarao; break; }

Toda vez que um case passa atravs (no inclui a instruo break), adicione um comentrio onde a instruo break normalmente estaria. 1.5.9 Declarao try-catch Uma declarao try-catch deve seguir a seguinte forma;
try { declarao; } catch (ExceptionClass e) { declarao; }

1.6. Espaos em Branco 1.6.1. Linhas em branco Linhas em branco melhoram a legibilidade definindo sees de cdigo que so relacionadas logicamente. Duas linhas em branco devem sempre ser usadas nas seguintes circunstancias. - Entre sees de arquivos de um arquivo de cdigo 7

- Entre as definies de classe e interfaces Uma linha em branco devem sempre ser usadas nas seguintes circunstancias. - Entre mtodos - Entre as variveis locais em um mtodo e sua primeira declarao - Antes de um comentrio de bloco ou comentrio de linha - Entre sees lgicas dentro de um mtodo para melhorar a legibilidade 1.6.2. Espaos em branco Espaos em branco devem sempre ser usadas nas seguintes circunstancias. - Uma palavra chave seguida por um parentese deve ser separada por um espao. Exemplo:
while (true) { ... }

Note que um espao em branco no deve ser usado entre o nome do mtodo e a abertura de parenteses. Isto ajuda a distinguir palavras-chave de chamadas de mtodos. - Uma linha em branco deve aparecer depois da virgula em uma lista de argumentos. - Todo o operador binrio exceto "." deve ser separado de outros operadores por espao. Espao em branco nunca devem separar operadores unrios, como incremento (++) e decremento (--) de seus operandos. - As expresses em uma declarao for deve ser separada por espao em branco. - Cats devem ser sempre seguidos por um espao em branco. 1.7. Convenes de Nomes Convenes de nomes tornam os programas mais compreensveis tornando-os mais fceis de ler. Elas tambm podem fornecer informao sobre a funo do identificador.

Tipo de Identificador Classes e Interfaces

Regras para Nomenclatura Os nomes de classe devem ser substantivos, com a primeira letra de cada palavra interna em maiscula. Tente manter seus nomes de classe simples e descritivos. Evite siglas e abreviaes (a menos que a sigla seja muito mais usada do que a forma longa, como a URL ou HTML) . Mtodos devem ser verbos, em maisculas e minsculas com a primeira letra minscula, com a primeira letra de cada palavra interna em maiscula. Devem iniciar com minscula. Palavras internas comeam com letras maisculas. No deve comear com underline ou $, mesmo que ambos sejam permitidos. Use nomes curtos, mas significativos. O nome deve indicar a inteno da utilizao da varivel. Os nomes comuns para variveis temporrias so i, j, k, m, n e para inteiros, c, d, e e para caracteres.

Exemplos class Raster; class ImageSprite; interface RasterDelegate; interface Storing;

Mtodos

run(); getBackground();

Variveis

int char float

i; *cq; myWidth;

Constantes

Constantes devem ter todas as letras maisculas separadas por underline "_".

int MIN_WIDTH = 4; int MAX_WIDTH = 999; int GET_THE_CPU = 1;

1.8. Prticas de Programao 1.8.1. Fornecer acesso a variveis de instancia e de classes No faa qualquer instancia ou varivel de classe public, sem uma boa razo. 1.8.2. Referindo-se a variveis e mtodos de classe Evite usar um objeto para acessar uma classe (static) ou mtodo. Use um nome de classe em vez disso. Por exemplo:
classMethod(); AClass.classMethod(); anObject.classMethod(); //OK //OK //EVITAR!

1.8.3. Constantes Constantes numricas no devem ser codificadas diretamente., exceto por -1, 0 e 1, que podem aparecer em um loop for como valor de contador. 1.8.4. Atribuies de Variveis Evite atribuir diversas variveis com o mesmo valor em uma nica instruo. difcil de ler. 9

No use o operador de atribuio em um lugar onde ele pode ser facilmente confundido com o operador de igualdade. 1.8.5. Parenteses geralmente uma boa ideia usar livremente parenteses numa expresso envolvendo operadores mistos para evitar problemas de precedncia de operadores. Mesmo se a precedncia do operador parecer clara para voc, ela no pode ser para outros.
if (a == b && c == d) // EVITAR! if ((a == b) && (c == d)) // CERTO

2. JAVADOC Puts.. para que eu vou utilizar Javadoc, no vou documentar ? OK, mas no necessariamente precisa usar o Javadoc para documentar. O Javadoc tem um padro de tags (que sar apresentado a seguir) que descrevem os mtodos e as classes, esse padro ajuda a deixar o cdigo mais claro e "limpo". Relembrando: Javadoc a ferramenta utilizada para criar arquivos HTML que documentam o cdigo Java. 2.1. Criando Documentao com Javadoc 2.1.1. Comentrios de documentao Antes que arquivos de HTML possam ser gerados com a ferramenta Javadoc, programadores devem inserir comentrios especiais - chamados comentrios de documentao. Como j foi visto, comentrios de documentao so constitudos por
/** * */

Uma vez que Javadoc utilizado para criar arquivos HTML, os comentrios de documentao podem ser inseridos com tags HTML. A seguir algumas das tags que podem ser usadas para formatar os comentarios. Texto <b> </b> <i> </i> <tt> </tt> <font size="12"> </font> <font color="black"> </font> <font face="Times New Roman"> Formatao <p> </p> <br /> paragrafo quebra de linha negrito itlico texto momo espaado Tamanho da letra Cor do texto Fonte do texto

10

2.1.2. Documentando o cdigo-fonte Java Os comentrios de documentao so colocados na linha antes de uma declarao de classe, uma declarao de interface, um construtor, um mtodo e um campo( ou seja, uma varivel de instancia ou de referencia). Tags @see @author @param @throws @return @deprecated {@link link} @since @version Significado See Also Author Parameters Throws Return Deprecaded Link Since Version Descrio Especifica outras classes relacionadas Especifica o autor da classe Especifica um parmetro para o construtor Especifica as excees lanadas por esse construtor Descreve o tipo de retorno do mtodo. Informa se esse mtodo est depreciado, ou seja, ir deixar de existir na prxima verso do programa Permite a insero de hiperlinks explcitos em outros documentos HTML Indica quando omtodo foi adicionado a classe Especifica a verso da casse ou mtodo

Um caractere # utilizado em vez de um ponto rotulamos um mtodo ou um campo. Isso cria um link ao nome do campo ou do mtodo que segue o caractere #. Pela conveno do Javadoc, os programadores compem o cdigo-fonte (isto , palavras chave , identificadores e expresses) com os tags de HTML <code> e </code>. A seguir um exemplo de uso das tags do Javadoc
// Fig. H.1: Time.java // Declarao da classe Time com os mtodos set e get. package appH.com.deitel.jhtp6.appenH; // coloca a classe Time em um pacote /** * Essa classe mantm a hora no formato de 24 horas. * @see java.lang.Object * @author Deitel & Associates, Inc. */ public class Time { private int hour; // 0 - 23 private int minute; // 0 - 59 private int second; // 0 - 59 /** * O construtor Time sem argumento inicializa cada varivel de instncia * como zero. Isso assegura que objetos Time iniciem em um estado * consistente. @throws Exceo no caso de uma data/hora invlida */ public Time() throws Exception { this(0, 0, 0); // invoca o construtor Time com trs argumentos } // fim do construtor Time sem argumento

11

/** * Construtor Time * @param h a hora * @throws Exceo no caso de uma data/hora invlida */ public Time(int h) throws Exception { this(h, 0, 0); // invoca o construtor Time com trs argumentos } // fim do construtor Time de um argumento. /** * Construtor Time * @param h a hora * @param m o minuto * @throws Exceo no caso de uma data/hora invlida */ public Time(int h, int m) throws Exception { this(h, m, 0); // invoca o construtor Time com trs argumentos } // fim do construtor Time de trs argumentos /** * Construtor Time * @param h a hora * @param m o minuto * @param s o segundo * @throws Exceo no caso de uma data/hora invlida */ public Time(int h, int m, int s) throws Exception { setTime(h, m, s); // invoca setTime para validar a data/hora } // fim do construtor Time de trs argumentos /** * constructor Time * @param time Um objeto Time com o qual inicializar * @throws Exceo no caso de uma data/hora invlida */ public Time(Time time) throws Exception { // invoca o construtor Time com trs argumentos this(time.getHour(), time.getMinute(), time.getSecond()); } // fim do construtor Time com o argumento Time /** * Configura um novo valor de usando hora universal. Verifica * validade dos dados. Configura valores invlidos como zero. * @param h a hora * @param m o minuto * @param s o segundo * @see com.deitel.jhtp6.appenH.Time#setHour * @see Time#setMinute * @see #setSecond * @throws Exceo no caso de uma data/hora invlida */ public void setTime(int h, int m, int s) throws Exception { setHour(h); // configura hour setMinute(m); // configura minute setSecond(s); // configura second } // fim do mtodo setTime /**

12

* Configura a hora. * @param h a hora * @throws Exceo no caso de uma data/hora invlida */ public void setHour(int h) throws Exception { if (h >= 0 && h < 24) { hour = h; } else { throw (new Exception()); } } // fim do mtodo setHour /** * Configura o minuto. * @param m o minuto * @throws Exceo no caso de uma data/hora invlida */ public void setMinute(int m) throws Exception { if (m >= 0 && m < 60) { minute = m; } else { throw (new Exception()); } } // fim do mtodo setMinute /** * Configura o segundo. * @param s o segundo. * @throws Exceo no caso de uma data/hora invlida */ public void setSecond(int s) throws Exception { if (s >= 0 && s < 60) { second = s; } else { throw (new Exception()); } } // fim do mtodo setSecond /** * Obtm a hora. * @return um <code>integer</code> especificando a hora. */ public int getHour() { return hour; } // fim do mtodo getHour /** * Obtm o minuto. * @return um <code>integer</code> especificando o minuto. */ public int getMinute() { return minute; } // fim do mtodo getMinute /** * Obtm o segundo. * @return um <code>integer</code> especificando o segundo. */ public int getSecond() {

13

return second; } // fim do mtodo getSecond /** * Converte para String no formato de data/hora universal * @return uma representao de <code>string<code> * da data/hora no formato de data/hora universal */ public String toUniversalString() { return String.format( "%02d:%02d:%02d", getHour(), getMinute(), getSecond()); } // fim do mtodo do toUniversalString /** * Converte para String no formato de data/hora padro * @return uma representao de <code>string<code> * da data/hora no formato padro de data/hora */ public String toStandardString() { return String.format("%d:%02d:%02d %s", ((getHour() == 0 || getHour() == 12) ? 12 : getHour() % 12), getMinute(), getSecond(), (getHour() < 12 ? "AM" : "PM")); } // fim do mtodo toStandardString } // fim da classe Time /************************************************************************** * (C) Copyright 1992-2005 by Deitel & Associates, Inc. and * * Pearson Education, Inc. All Rights Reserved. * * * * DISCLAIMER: The authors and publisher of this book have used their * * best efforts in preparing the book. These efforts include the * * development, research, and testing of the theories and programs * * to determine their effectiveness. The authors and publisher make * * no warranty of any kind, expressed or implied, with regard to these * * programs or to the documentation contained in these books. The authors * * and publisher shall not be liable in any event for incidental or * * consequential damages in connection with, or arising out of, the * * furnishing, performance, or use of these programs. * *************************************************************************/

2.2. Gerando a documentao Javadoc no NetBeans Esta a parte mais difcil at agora ! -Selecione o seu projeto. -Clique com o boto direito sobre o mesmo. -V at a opo Gerar Javadoc e clique nela. Ser gerada por padro na pasta dist/Javadoc do seu projeto. 3. CONVENES SQL Utiliza-se por conveno as palavras chaves do SQL em maisculas e os identificadores dos objetos em minsculas. Exemplo:

14

SELECT campo1,campo2 FROM table1 WHERE campo1 = 'Teste';

4. CONFIGURANDO OS MODELOS DO NETBEANS O NetBeans vem com modelos de classe genricos. Mas voc pode configur-los para que fiquem de acordo com as normas da sua empresa ou ainda com as suas. Para configurar os modelos v em Ferramentas > Modelos > Java

Aqui voc tem varias opes pode criar uma classe a partir de um modelo ou pode editar um modelo padro ou ainda pode importar um arquivo .java (mas no qualquer arquivo, um modelo) . 4.1. FreeMaker A partir do NetBeans IDE 6.0, possvel usar opcionalmente a linguagem de modelo FreeMarker para definir os modelos de arquivo. Vrios dos modelos includos no IDE so definidos dessa forma. Algumas tags podem ser usadas em modelos, entre elas : Tag ${date} ${encoding} ${name} ${nameAndExt} ${package} ${time} ${user} insere a data atual insere a codificao padro insere o nome do arquivo. insere o nome do arquivo, junto com sua extenso. insere o nome do pacote em que o arquivo criado. insere a hora atual insere o nome do usurio Descrio

15

Para mais informaes sobre FreeMaker consulte:http://platform.netbeans.org/tutorials/60/nbmfiletemplates_pt_BR.html 4.2. Exemplos de modelos No meu casso eu apenas alterei o modelo Classe Java e Classe Java Principal. Eles ficaram assim: Classe Java

/** Classname: * * Version information: * * Date: * * author: * Copyright notice: */

${nameAndExt} (verso) ${date} - ${time} ${user} (informaes do mtodo, pra que serve, idia principal)

<#if package?? && package != ""> package ${package}; </#if> /** * Descrio * @see * @author ${user} */ public class ${name} { }//fim da classe ${name}

16

Classe Principal Java

/** Classname: * * Version information: * * Date: * * author: * Copyright notice: */

${nameAndExt} (verso) ${date} - ${time} ${user} (informaes do mtodo, pra que serve, idia principal)

<#if package?? && package != ""> package ${package}; </#if> /** * Descrio * @see * @author ${user} */ public class ${name} { public static void main(String[] args) { }//fim do mtodo main }//fim da classe ${name}

________________________________________________________________________________ REFERENCIAS Java Code Convertions, Sun http://java.sun.com/docs/codeconv/CodeConventions.pdf DEITEL Java: Como programar, 6 Edio ,Apndice H . http://lcadfs2.lcad.icmc.usp.br/~junio/mat/Javadoc.pdf Customize Your NetBeans Java Template to Fit Your Need , Athur Cheng http://netbeans.org/competition/win-with-netbeans/customize-java-template.html

17