Estilo de formatao padro (Conveno de Cdigo) e Documentao (JavaDoc)

Conveno de Cdigo so regras e sugestes para que os cdigos fiquem padronizados, com isso, tambm fiquem de fcil compreenso. Usaremos o padro da Sun, s que com certas adaptaes, pois nele h uma srie de sugestes que sero tomadas como regras. Javadoc uma ferramenta para gerar documentao de API(Application Programming Interface) em formato HTML de comentrios doc presentes no cdigo-fonte. H vrios aplicativos que colocam o programa nos padres da Sun ou num padro configurado, esses softwares so chamados de Code Beautifiers, porm no os vejo como a melhor opo, pois eles no iro documentar, s iro cuidar de espaamentos, parnteses e semelhantes. Escrevendo no padro voc se acostumar a ler no padro com maior facilidade, o que com o tempo se tornar algo mecnico. A padronizao e documentao facilitaro na compreenso do cdigo, o que ir nos economizar bastante tempo, sendo que dificilmente o software vai ter sempre a manuteno pelo autor original. Se o tornarmos o cdigo fonte um produto, temos que ter certeza que est bem claro e coeso. Vejo um exemplo de cdigo de cdigo, que est disponvel na endereo: http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182
/* * @(#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * 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. */ package java.blah; import java.blah.blahdy.BlahBlah; /** * Class description goes here. * * @version 1.82 18 Mar 1999 * @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; /** * ...constructor 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... } }

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

Organizao dos arquivos Cada cdigo fonte deve conter uma nica classe ou interface. Quando classes ou interfaces privadas esto associadas com classes pblicas, voc pode colocar ela no mesmo arquivo. A classe ou interface pblica deve vir primeira. Todos os cdigos fontes devem vim com comentrios estilo c que listam o nome da classe, verso, data e aviso copyright:

A primeira linha no comentada deve ser a instruo package. Depois disso, a instruo import, se necessrio:
package java.awt;

import java.awt.peer.CanvasPeer;

Veja que o cdigo-fonte segue uma ordem padro: 1-Comentrio da classe ou interface. 2-Instruo da classe ou interface. 3-Comentrio de implementao da classe ou interface, o que no foi conveniente colocar no primeiro comentrio. 4-Variveis estticas 5-Variveis de instncia. 6-Construtores 7-Mtodos, esses podem ser agrupados por funcionalidade de preferncia por escopo ou acessibilidade. Por exemplo, um mtodo de classe privada pode estar entre dois mtodos pblicos. O importante melhorar a leitura e o entendimento do cdigo. Evite linhas com mais de 80 caracteres. Quando uma expresso no couber numa linha, quebre-a de acordo com os seguintes princpios: Quebre depois de uma vrgula. Quebre antes de um operador. Prefira quebras de nveis mais alto do que de nveis mais baixos. Alinhe uma nova linha no comeo de uma expresso no mesmo nvel que a linha anterior. Se as regras anteriores levaram a um cdigo confuso ou que est passando da margem direita, apenas distancie 8 espaos(normalmente 2 tabulaes).

someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3)); longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; //Forma convencional someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } //Aqui a regra no funciona, ento simplesmente //foi dado 8 espaos da margem private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma;

Seguem alguns exemplos:

Perceba que depois da quebra de linha, as instrues continuam depois do operador. Comentrios Existem dois tipos de comentrios em Java, os de implementao e de documentao. Os comentrios de implementao so aqueles encontrados em C++ delimitados por // ou /*..*/. Os comentrios de documentao so exclusivos do Java e so delimitados por /**...*/ que so os Javadocs, mas iremos falar sobre isso depois. Programas podem ter quatro estilos de comentrios de implementao: bloco, nica linha, rastro e fim da linha. Comentrios de bloco servem para descrever arquivos, mtodos, estrutura de dados e algoritmos. Eles podem ser usados no comeo de cada arquivo e antes de cada mtodo. Eles tambm podem ser usados em outros lugares como dentro de mtodos, quando internos a um mtodo ou funo, eles devem estar na mesma distncia da margem que o cdigo descrito pelos mesmos.
/* * Here is a block comment. */

if (condition) {

Comentrios de nica linha so pequenos comentrios que se no podem ser escritos em uma linha se tornam comentrios de bloco. Um comentrio de nica linha deve preceder por uma linha vazia. Olhe um exemplo:
/* Handle the condition. */ ...

Comentrios de rastro so comentrios curtos que aparecem na mesma linha do cdigo que descrevem, mas devem ficar afastados da instruo. Se mais de um aparece na mesma parte do cdigo, eles

if (a == 2) { return TRUE; } else { return isPrime(a); }

devem ficar no mesmo alinhamento.

/* special case */ /* works only for odd a */

Os comentrios de fim de linha usam o delimitador // que pode comentar uma linha inteira ou parcialmente. Eles no devem ser usados para fazer comentrios de muitas linhas, mas podem ser usados para comentar partes do cdigo.
if (foo > 1) { // Do a double-flip. ... } else { return false; // Explain why here. } //if (bar > 1) { // // // Do a triple-flip. // ... //} //else { // return false; //}

Colocar uma declarao por linha recomendado, pois encoraja o comentrio.

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

No deve colocar dois tipos diferentes na mesma linha:

int foo, fooarray[]; //WRONG!

Tente sempre que possvel iniciar uma varivel local onde ela declarada. Coloque declaraes somente no comeo de um bloco. (Um bloco qualquer cdigo cercado por chaves { e }) No espere para declarar variveis at que tenha o seu primeiro uso, isso pode confundir um programador descuidadoso. E no declare variveis com o mesmo nome em blocos internos.
void myMethod() { int int1 = 0; if (condition) { int int2 = 0; ... } // beginning of method block // beginning of "if" block

Uma exceo regra so os ndices dos laos for, os quais no Java podem ser declarados na instruo.
for (int i = 0; i < maxLoops; i++) { ... }

class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ...

Quando estiver programando classes e interfaces em Java, siga as seguintes regras de formatao: * Sem espao entra os nomes dos mtodos e os parnteses ( comeando a lista de parmetros. * A chave aberta { aparece no fim da mesma linha da declarao. * A chave fechada } comea uma linha que esteja alinhada com o declarao que o abriu, exceto uma instruo nula, vazio, ele deve aparecer logo aps o {

Instrues simples devem aparecer uma em cada linha. Instrues compostas que so listas de instrues enclausurada em chaves "{ instrues }" devem seguir a seguintes regras: * A instruo enclausurada deve estar um nvel acima da instruo composta * A chave aberta deve estar no fim da linha que comea a instruo composta; a chave fechada deve estar no mesmo alinhamento do comeo da instruo composta * Chaves so usadas em todas as instrues, mesmo de uma s linha. Isso facilita colocar instrues sem causar erro de esquecer de colocar chaves. A instruo return no precisa conter parnteses, ao menos que isso ajude na compreenso da instruo.
return; return myDisk.size(); return (size ? size : defaultSize); if (condition) { statements; } if (condition) { statements; } else { statements; } if (condition) { statements; } else if (condition) { statements; } else { statements; } for (initialization; condition; update) { statements; } while (condition) { statements; } while (condition); do { statements; } while (condition); switch (condition) { case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; }

Toda vez que acontecer um falls through (no incluir a instruo break), acrescente um comentrio onde a instruo break estaria. Isso est presente no cdigo acima.
try { statements; } catch (ExceptionClass e) { statements;

} try { statements; } catch (ExceptionClass e) { statements; } finally { statements; }

Linhas em branco melhoram a leitura do cdigo por separar partes do cdigo logicamente relacionadas. Duas linhas em branco devem sempre ser usadas nas seguintes circunstncias: * Entre sees do cdigo fonte * Entre definio de classes e interfaces Uma linha em branco deve ser sempre usada nas seguintes circunstancias: * Entre mtodos * Entre variveis locais nos mtodos e sua primeira instruo * Antes de um comentrio de bloco ou de uma nica linha * Entre sees logicamente relacionadas dentro de um mtodo para melhor a leitura Uma palavra chave que seguido de parnteses como while ou if devem ter um espao entre o nome e o parnteses. Lembre-se de no usar espaos na chamada de mtodos, justamente para ajudar a diferencilos das palavras chaves seguidas de parnteses. Um espao em branco deve aparecer depois das vrgulas. Todos operadores binrios devem ser separados por espao exceto o .. Mas nunca se separa operadores unary como incremento (++) ou decremento (--). Expresses no lao for devem ser separadas por espao e instruo de forar tipo tambm.
a += c + d; a = (a + b) / (c * d);

while (d++ = s++) { n++; } printSize("size is " + foo + "\n"); for (expr1; expr2; expr3) myMethod((byte) aNum, (Object) x); myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

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

Regras de nomeao Pacotes devem ter sempre seu nome em letras minsculas. Classes e interfaces devem ter todas as letras minsculas, exceto a primeira letra de cada palavra interna ao nome deve ser maiscula. Tente fazer o nome ser simples e descritivo. Use palavras completas, evite abreviaes. Mtodos funcionam como as classes, s que a primeira palavra interna tem a primeira letra minscula e eles so verbos, aes. Variveis devem ter nomes pequenos e significativos, seguindo a mesma padronizao dos mtodos. No se deve usar variveis com uma s letra, a menos que seja uma varivel descartvel como ndices do lao for ou outro tipo de estrutura que necessita de uma varivel. Nomes comuns para variveis temporrias so i, j, k, m, e n para inteiros; c, d e e para caracteres. Constantes devem vir em letras maisculas e se for separar palavras use o _. Prticas de Programao No faa variveis de instancia ou de classe pblicas sem uma boa razo. Evite chamar uma mtodo de classe (mtodo esttico) por uma instancia. Constantes numricas no devem ser codificadas diretamente, exceto o -1, 0 e 1. No atribua vrias variveis na mesma linha, difcil de ler. No use atribuies em lugares onde ele pode ser facilmente confundido com um operador de igualdade.

if (c++ = d++) { ... }

// AVOID! (Java disallows)

Deveria ser assim

if ((c++ = d++) != 0) { ... }

Uso de parentes deve ser usado liberadamente para facilitar que o cdigo fique mais fcil de ler:
if (a == b && c == d) // ERRADO! if ((a == b) && (c == d)) // CERTO

Retorno de valores
if (booleanExpression) { return true; } else { return false; }//ERRADO

Deveria ser escrito assim:

return booleanExpression;//CERTO

Outro exemplo:
if (condition) { return x; } return y;//ERRADO

deveria ser escrito assim:

return (condition ? x : y);//CERTO

Agora volte no exemplo do comeo e d uma olhada, e perceba as regras. XD JAVADOC! Vamos dar uma olhada agora no JavaDoc: Um comentrio doc escrito em HTML e deve preceder uma classe, campo, construtor ou mtodo. feito por duas partes, uma descrio seguida de um bloco de tags. As tags usadas no exemplo seguinte so @param, @return, and @see.
/** * Retorna a imagem de um objeto que pode ser desenhado na tela. * O argumento url deve especificar um link absoluto {@link URL}. O argumento * name quem especifica o que est ligado ao argumento url. * <p> * Esse mtodo sempre retorna imediatamente, se a imagem existe ou no * Quando a applet tenta desenhar uma imagem na tela, * as informaes sero carregadas. Os grficos primitivos * que desenham a imagem vo pintar a imagem na tela. * * @param url uma URL absoluta que d a localizao base da imagem * @param name a localizao da imagem relativa ao argumento url. * @return a imagem especificada * @see Image */ public Image getImage(URL url, String name) { try { return getImage(new URL(url, name)); } catch (MalformedURLException e) { return null; } }

# Cada linha est alinhado com o cdigo abaixo do comentrio.. # A primeira linha contem o delimitador do contedo (/**). # Desde o Javadoc 1.4, os asteriscos antes das linhas so opcionais, mas so usados, pois deixam melhoram o visual. # Escreva a primeira frase como uma breve resumo do mtodo, o Javadoc automaticamente coloca isso no sumrio do mtodo. # Veja que a tag inline {@link URL}, que converte um hyperlink HTML direcionado a documentao da

classe URL. Essa tag inline pode ser usada em qualquer lugar que um comentrio pode ser escrito. # Se voc tem mais de um pargrafo no comentrio doc, separe os pargrafos com a tag de pargrafo <p> como mostrado. # Insira uma linha em branco entre a descrio e a lista de tags. # A primeira linha que comea o caractere @ termina a descrio. H s uma descrio por bloco de comentrio doc. # A ultima linha contem o delimitador de fim de comentrio (*/), diferente do que inicia, ele s tem um asterisco. # possvel utilizar tags HTML na descrio, caso queira aprender: http://www.w3schools.com/html/default.asp Tags: @param: deve ser colocada, e serve para descrever os parmetros da funo @return: se o mtodo no for void, ele necessrio e descreve o que retornado @throws: a tag deve ser includa para qualquer exceo
/** * @throws IOException If an input or output * exception occurred */ public void f() throws IOException { // body }

@author: diz o autor da classe, sendo que pode haver vrios. @version: diz a verso do cdigo @see: faz referencia a uma outra pgina como um Veja Tambm @since: Diz para qual verso da API do Java o aplicativo foi feito. @deprecated: Diz quando um mtodo foi depreciado e qual est em seu lugar. Essa notao indica que no deve usar esse recurso da classe, pois j h alternativas melhores.
/** * @deprecated * */ As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}

Caso queira mais informaes: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html [Em ingls] http://java.sun.com/j2se/javadoc/writingdoccomments/index.html [Em ingls]