CONVENO DE CDIGO JAVA

Eligiane Ceron - Abril de 2012 Verso 1.0

Contedo
Consideraes iniciais ........................................................................................................... 2 Introduo ............................................................................................................................ 2 Extenso de arquivos ............................................................................................................ 2 Arquivos de cdigo Java ........................................................................................................ 2 Comentrios iniciais .......................................................................................................... 2 Declaraes de pacotes e importaes .............................................................................. 2 Declarao da classe/interface .......................................................................................... 3 Identation (recuo) de cdigo .................................................................................................3 Quebras de linha ............................................................................................................... 3 Sobre comentrios ................................................................................................................ 4 Comentrios de implementao ........................................................................................ 5 Comentrios de documentao ......................................................................................... 6 Declaraes .......................................................................................................................... 6 Espaos em branco ............................................................................................................... 6 Linhas em branco .............................................................................................................. 6 Espaos em branco............................................................................................................ 6 Convenes de Nomenclatura ............................................................................................... 7 REFERNCIAS ........................................................................................................................ 7

Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

Consideraes iniciais
Este texto uma traduo adaptada da conveno de cdigo Java publicada pela Sun e mantida pela Oracle. Voc pode ler o material original no link que se encontra no tpico Referncias.

Introduo
A padronizao de cdigo conveniente devido a vrios aspectos. Segundo estatsticas, cerca de 80% do tempo gasto com desenvolvimento de software referente manuteno do sistema. E dificilmente os softwares desenvolvidos so mantidos pelos seus autores. A padronizao ajuda a deixar o cdigo mais legvel, facilitando assim o entendimento do mesmo por parte de novos integrantes da equipe de desenvolvimento.

Extenso de arquivos
Os softwares java usam dois tipos de arquivos: os arquivos de cdigo, que recebem a extenso .java e os bytecodes que recebem a extenso .class. O bytecode gerado pelo compilador Java.

Arquivos de cdigo Java

Um arquivo Java composto por sees que devem ser separadas por linhas em branco, podendo utilizar tambm comentrios para identificar cada uma. Cada arquivo de cdigo java deve conter uma nica classe ou interface pblica. Arquivos com mais de duas mil linhas de cdigo devem ser evitados, pois ficam muito pesados. A organizao bsica de um arquivo de cdigo Java deve obedecer seguinte ordem: 1. Comentrios iniciais 2. Declaraes de pacotes e importaes 3. Declarao da classe/interface Comentrios iniciais Todo arquivo de cdigo deve iniciar com comentrios de incio, que devem conter informaes a respeito da classe/interface, como por exemplo, nome da classe, informaes de verso, data e autor. Exemplo: /** * Nome da classe * * @version v 2.0 Janeiro/2012 * @author CERON, Eligiane */ Declaraes de pacotes e importaes A primeira linha de cdigo aps os comentrios iniciais deve ser a declarao do pacote (se necessrio), e em sequncia as declaraes de importaes. Exemplo:
Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

package pacote1; import java.util.Scanner; import java.util.ArrayList;

Declarao da classe/interface A tabela abaixo mostra cada parte de uma classe/interface, na ordem em que elas devem aparecer. 1 2 3 4 5 6 7 Comentrio de documentao (/** ..... */) Declarao da classe/interface Comentrios de implementao da classe (/* .... */) Atributos estticos Demais atributos Construtores Demais mtodos Observaes

Se necessrio aqui pode ser inserido algum comentrio a respeito da classe Inicialmente os pblicos, depois os protegidos e por ltimo os privados Inicialmente os pblicos, depois os protegidos e por ltimo os privados Agrupe os mtodos por funcionalidade, exemplo: getters, setters, mtodos de validao, mtodos de clculos, etc.

Identation (recuo) de cdigo

Os recuos so utilizados para alinhar visualmente comandos pertencentes a blocos de cdigo. Um bloco o cdigo envolvido pelos delimitadores { e }, como por exemplo o if. A regra geral abrir o bloco na linha do comando e fechar alinhado a ele. Exemplo: if (condicao){ //comandos }else{ //comandos } Normalmente se utiliza 4 espaos como medida padro da tabulao, porm algumas vezes necessrio utilizar 8 espaos para obter uma visualizao melhor do cdigo. Devem ser evitadas linhas com mais de 80 caracteres. Quebras de linha Quando uma expresso no couber numa nica linha, quebr-la de acordo com as seguintes regras bsicas: Aps uma vrgula Antes de um operador Alinhar a nova linha com o incio da expresso da linha anterior Se as regras acima gerarem cdigo confuso, ou se a linha de baixo ficar colada na margem, use uma tabulao de 8 espaos.

Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

Alguns exemplos de quebra de linha numa chamada de mtodo:

executarMetodo(parametro1, parametro2, parametro3, parametro4, parametro5);//usando 8 espaos int res = executarMetodo(parametro1, parametro2, parametro3, parametro4, paramentro5); //alinhando com o inicio expresso anterior

da

Exemplo de quebra de linha numa expresso aritmtica: double res = valor1 * (valor2 + valor3) + valor4 / valor5;

Para inserir quebras de linha em condies nos ifs, por exemplo, cuide para no alinhar as condies com os comandos, pois eles se misturariam visualmente e tornaria ruim a leitura do cdigo. Exemplo 1: EVITAR if(condicao1 && condicao2 || condicao3 && condicao4){ executarAlgo(); }

Exemplo 2: PREFIRA if(condicao1 && condicao2 || condicao3 && condicao4){ executarAlgo(); }

Sobre comentrios
Programas desenvolvidos em Java podem ter dois tipos de comentrios: comentrios de implementao e comentrios de documentao. Os comentrios de implementao so os mesmo da linguagem C++, que so delimitados por /* ... */, e //. Os comentrios de documentao (conhecido como "comentrios doc") so Java-only, e so delimitados por / ** ... * /. Comentrios de documentao podem ser extrados para arquivos HTML usando a ferramenta javadoc. Comentrios de implementao so aqueles destinados a comentar o cdigo ou a aplicao em si. Comentrios de documentao so destinadas a descrever a especificao do cdigo, a partir de uma perspectiva de implementao livre, para ser lido por desenvolvedores que no necessariamente possuem o cdigo fonte em mos. Os comentrios devem ser usados para dar uma viso geral do cdigo e fornecer informaes adicionais que no est prontamente claro no prprio cdigo. Eles devem conter apenas informaes relevantes para a leitura e compreenso do programa. Por exemplo, informaes sobre como o pacote correspondente construdo ou em qual diretrio ele reside no deve ser includo como um comentrio.
Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

Comentrios de implementao H quatro possveis formatos de comentrio de implementao: bloco, linha, direita e no fim da linha. Os comentrios de bloco so utilizados para descrever arquivos de cdigo, mtodos ou algum algoritmo dentro de um mtodo. Procure sempre inserir uma linha em branco antes do bloco de comentrios. Exemplo de comentrio de bloco:

/ * * Aqui est um comentrio de bloco. * /

Os comentrios de linha so para comentrios curtos, e devem ser precedidos com uma linha em branco, assim como o comentrio de bloco. if (condicao){ /* comentrios */ executarAlgo(); }

Comentrios muito curtos podem aparecer na mesma linha do cdigo que descrevem, mas devem ser deslocados o suficiente para separ-los das declaraes. Se mais de um breve comentrio aparecer em um pedao de cdigo, todos eles devero ser recuados de modo a se alinharem. Exemplo: if (condicao) { return valor1; } else { return outroValor; }

/* comentrio 1*/ /* comentrio 2 */

O delimitador de comentrio // pode servir para comentar toda uma linha ou apenas parte dela. Evite utiliz-los quando muitas linhas de comentrio so necessrias (prefira o delimitador de bloco). No entando, ele pode ser utilizado em vrias linhas para comentar ou anular um trecho de cdigo.
if (condicao) { // comentrio. ... } else { return false; // Explicao aqui. } //if (condicao2) { Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

// // return ... //} //else { // return false; //}

Comentrios de documentao Os comentrios de documentao possuem regras especficas e sero abordados em um prximo artigo.

Declaraes
Ao declarar variveis, observe as seguintes regras: Faa apenas uma declarao por linha, de modo a incentivar o uso de comentrios Inicialize apenas uma varivel por linha Use letras minsculas e evite caracteres especiais.

Espaos em branco
Linhas em branco A funo das linhas em branco prover maior legibilidade de cdigo e organizao. Utilize duas linhas em branco para separar sees em um arquivo fonte e entre definies de classe e interfaces. Use uma linha em branco entre mtodos, aps declarar variveis, antes de um bloco ou linha de comentrio ou mesmo dentro de um bloco de cdigo para separar comandos em comum. Espaos em branco Sempre que uma palavra reservada da linguagem for seguida de parnteses, deve conter um espao separando-os. while (condio){ //comandos } No utilize espao entre um mtodo e seus parnteses: public void executarAlgo(){ .... Use um espao em branco aps a vrgula numa lista de argumentos e nas expresses aritmticas utilize um espao em branco para separar operandos de seus operadores. a = b + c; //ok! a=b+c; //evitar!

Separe tambm operadores relacionais das condies if(condicao1 && condicao2){

Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.

Convenes de Nomenclatura
Pacotes Classes e interfaces Letras minsculas sem caracteres especiais 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. Constantes devem ter todas as letras maisculas separadas por underline gui class Pessoa class ContaCorrente

Mtodos

calcularAlgo()

Variveis

idade nomeCompleto

Constantes

MAX_SIZE VALOR_PADRAO

REFERNCIAS
ORACLE. CodeConventions for the Java TM ProgrammingLanguage. 1999. Disponvel em: http://www.oracle.com/technetwork/java/codeconvtoc-136057.html ORACLE. Java SE Specifications. 2012. Disponvel em <http://docs.oracle.com/javase/specs/>

Copyright 1995-1999 Sun Microsystems, Inc. All rights reserved. Used by permission.