Convenções para Codificação Java Tradução: Jefferson Araujo Sun Microsystems Bibliografia: Oracle – Sun
Índice 1.
INTRODUÇÃO ............................................................................................................ 4 1.1 POR QUE UTILIZAR CONVENÇÃO DE CÓDIGO ?............................................. ?................................................................. .................... 4 1.2 POR QUE UTILIZAR CONVENÇÃO DE CÓDIGO ?............................................. ?................................................................. .................... 4
2.
NOMES DE ARQUIVOS ............................................................................................ 5 2.1 ARQUIVOS DE SUFIXOS .................................................... .................................................................................................. .............................................. 5 2.2 N 2.2 NOMES DE ARQUIVOS COMUNS ..................................................................................... 5
3. 4.
ORGANIZAÇÃO DE ARQUIVOS ............................................................................ ............................................... ............................. 5 ARQUIVOS-FONTE JAVA J AVA .................................................. ........................................................................................ ...................................... 6 4.1 COMENTÁRIOS I NICIAIS ............................................................................. ................................................................................................. .................... 6 4.2 DECLARAÇÕES DE PACOTES E IMPORTAÇÕES ............................................................... ................................................................. 6 4.3 DECLARAÇÕES DE CLASSE E DE I NTERFACE .............................................. .................................................................. .................... 7
5.
INDENTAÇÃO ...................................................... .......................................................................................................... ....................................................... ... 8 5.1 COMPRIMENTO DA LINHA ............................................... .............................................................................................. ............................................... 8 5.2 EMPACOTANDO LINHAS.................................................. ................................................................................................. ............................................... 8
6.
COMENTÁRIOS ....................................................................................................... 10 6.1 FORMATOS DE COMENTÁRIOS DE IMPLEMENTAÇÃO .................................................... 10 6.1.1 COMENTÁRIOS DE BLOCO ..................................................... ......................................................................................... .................................... 11 6.1.2 COMENTÁRIOS DE LINHA-Ú NICA ................................................... .............................................................................. ........................... 11 6.1.3 COMENTÁRIOS DE TRILHA ........................................................................................ 12 6.1.4 COMENTÁRIOS DE FINAL DE LINHA ................................................................ .......................................................................... .......... 12 6.2 COMENTÁRIOS DE DOCUMENTAÇÃO................................................. ............................................................................ ........................... 12
7.
DECLARAÇÕES ....................................................................................................... 14 7.1 N 7.1 NÚMERO POR LINHA ........................................................ .................................................................................................... ............................................ 14 7.2 LOCALIZAÇÃO ............................................................................................................. 14 7.3 I NICIALIZAÇÃO ............................................................................................................ 15 7.4 DECLARAÇÕES DE CLASSE E I NTERFACE ................................................... ..................................................................... .................. 15
8.
DECLARAÇÕES / COMANDOS .................................................. ............................................................................. ........................... 16 8.1 COMANDOS SIMPLES ................................................................................................... 16 8.2 COMANDOS COMPOSTOS .................................................................. ............................................................................................. ........................... 16 8.3 COMANDO DE R ETORNO ............................................................................. . 17 ETORNO (RETURN) .............................................................................. 8.4 COMANDOS ―IF‖, ―IF-ELSE‖, ―IF-ELSE-IF-ELSE‖ ................................................... ........................................................... ........ 17 8.5 COMANDOS ―FOR ‖ ..................................................................................... ....................................................................................................... .................. 17 8.6 COMANDOS ―WHILE‖ ................................................................................. ................................................................................................... .................. 18 8.7 COMANDO ―DO-WHILE‖ ............................................................................................... 18 8.8 COMANDO ―SWITCH‖ ....................................................... ................................................................................................... ............................................ 18 8.9 COMANDO ―TRY-CATCH‖ ................................................ ............................................................................................. ............................................. 19
9.
ESPAÇO EM BRANCO ............................................................................................ ............................................... ............................................. 19
9.1 LINHAS EM BRANCO .................................................................................................... 19 9.2 ESPAÇOS EM BRANCO .................................................................................................. 20
10. CONVENÇÕES DE NOMENCLATURA ........................................................... 21 11. PRÁTICAS DE PROGRAMAÇÃO ..................................................................... 23 11.1 FORNECENDO ACESSO À I NSTÂNCIA E VARIÁVEIS DE CLASSE................................... 23 11.2 R EFERINDO-SE A VARIÁVEIS DE CLASSE E MÉTODOS ................................................ 23 11.3 CONSTANTES ............................................................................................................. 23 11.4 ATRIBUIÇÕES DE VARIÁVEIS ..................................................................................... 23 11.5 PRÁTICAS DIVERSAS .................................................................................................. 24 11.5.1 PARÊNTESES ........................................................................................................... 24 11.5.2 VALORES DE R ETORNO ........................................................................................... 24 11.5.3 EXPRESSÕES ANTES DE ―?‖ NO OPERADOR CONDICIONAL ...................................... 25 11.5.4 COMENTÁRIOS ESPECIAIS ....................................................................................... 25 12. EXEMPLO DE CÓDIGO ...................................................................................... 25 12.1 EXEMPLO DE CÓDIGO FONTE JAVA............................................................................ 25
1. Introdução As convenções de código são uma boa prática de programação. Ajudam por exemplo na manutenção de um sistema. A violação dessas ―regras‖ prejudica e muito o
entendimento de uma API, por exemplo. Além do mais, com as convenções, podemos produzir um código legível e ―limpo‖, que demonstra qualidade de maneira profissional.
1.1 Por q ue u til izar c on ven ção d e códi go ? As convenções de código são importantes para os programadores por uma série de razões:
80 % do tempo gasto com o software vai para a manutenção; Dificilmente um software é mantido por toda sua existência pelo autor original; As convenções de código melhoram a legibilidade do software, fazendo com que engenheiros entendam o novo código mais rapidamente e por completo; Se um código fonte de programa deve ser enviado como um produto, é preciso ter certeza que ele está bem embalado, assim como qualquer outro produto.
Obs: Um ponto muito importante. Para que as convenções funcionem, todas as pessoas que escrevem software devem estar de acordo com as convenções, este é um processo que precisa ser divulgado desde a raiz para que TODOS tenham em mente estas boas práticas. 1.2 Por q ue u til izar c on ven ção d e códi go ? Esse documento reflete o padrão do código da linguagem JAVA apresentado no ―JAVA Language Specification‖, da Sun Microsytems (atual Oracle). As maiores contribuições são de Peter King, Patrick Naughton, Mike DeMoney, Jonni Kannerva, Kathy Walrath e Scott Hommel. Comentários devem ser enviados através de formulário para: http://java.sun.com/docs/forms/sendusmail.html
2. Nomes de Arquivos Essa seção lista os sufixos e nomes usados com maior freqüência.
2.1 Arquivo s de Sufixos O Software Java utiliza os seguintes sufixos:
Tipo de Arquivo Fonte Java Código de Byte Java
Sufixo .java .class
2 .2 N o m e s d e A r q u i v o s C o m u n s Nome do Arquivo GNUmakefile README
Uso O nome preferido para criação de arquivos. Usa-se GNUmake para construção do software. Nome preferido do arquivo que resume o conteúdo de um diretório particular
3. Organização de Arquivos Um arquivo consiste de seções que devem ser separadas por linhas em branco e um comentário opcional identificando cada seção. Arquivos com mais de 2000 linhas são pesados e devem ser evitados. Para ver um exemplo de programa Java corretamente formatado, veja o item 12.1.
4. Arquivos-Fonte Java Cada arquivo-fonte Java contém uma única classe pública ou de interface. Quando classes privadas e interfaces são associadas a uma classe pública, elas podem ser colocadas no mesmo arquivo-fonte da classe pública. A classe pública deve ser a primeira classe ou interface no arquivo. Arquivos-fonte Java seguem a seguinte ordem:
Comentários Iniciais (ver item 4.1); Declarações de pacotes e importes; por exemplo: import java.applet.Applet; import java.awt.*; import java.net.*;
Declarações de classe e de interface (ver item 4.3).
4.1 Com ent ári os Inic iais Todos os arquivos-fonte devem começar com um comentário ―c-style‖ que lista: nome da classe, versão, data, breve descrição do propósito do programa e direitos autorais. Por exemplo: /* * Nome da Classe: * * Informação da Versão: * * Data: * * Propósito do Programa: * * Direitos Autorais: */
4.2 Dec lar ações de Pac ot es e Im p or tações A primeira linha sem comentários da maioria dos arquivos-fonte Java é uma declaração de pacote. Após isso, podem ser realizadas as declarações de importação. Por exemplo: package java.awt; import java.awt.peer.CanvasPeer;
4.3 Declar ações de C las s e e de In terf ace A quadro a seguir descreve as partes de uma declaração de classe ou de interface, na ordem em que elas devem aparecer. Ver o exemplo do item 12.1 que inclui comentários.
1 2
3
4
5 6
7
Declaração de parte da Classe / Interface Comentários de documentação de classe / interface (/**...*/) Declaração de classe ou de interface
Notas Ver item “6.2 – Comentários de Documentação” para informação do que deve conter este comentário.
Esse comentário deve conter Comentário de qualquer informação a respeito da implementação de classe classe ou da interface não definida / interface (/**...*/), se no comentário de documentação de necessário classe ou interface. Primeiro as variáveis de classes públicas, depois as protegidas, após Variáveis de classe isso, o nível de empacotamento (estática) (sem modificação de acesso) e, aí sim, a classe privada. Primeiro as públicas, depois as Variáveis instanciáveis protegidas e então as privadas. Construtores Esses métodos devem ser agrupados por funcionalidade antes do que por escopo ou acessibilidade. Por exemplo, um Métodos método da classe privada pode estar entre dois métodos públicos. O objetivo é fazer com que a leitura e entendimento do código seja realizado mais facilmente.
5. Indentação Quatro espaços devem ser usados como unidade de indentação. A construção exata de indentação (espaços versus tabulações) não é especificada. Tabulações devem ser estabelecidas com 8 espaços (e não com 4).
5.1 Comp rimento da Lin ha Evitar linhas com mais de 80 caracteres, desde que estes não sejam manipulados por diversos terminais e ferramentas.
Obs.: Exemplos para uso em documentação deve ter menor comprimento de linha – geralmente não mais que 70 caracteres. 5.2 Empacotando L inhas Quando uma expressão não contiver uma única linha, a sua quebra deve ocorrer de acordo com alguns princípios:
A quebra deve ocorrer após uma vírgula; A quebra deve ocorrer antes de um operador; Dar preferência as quebras em níveis mais altos do que as de níveis mais baixos; Alinhar a nova linha com o começo da expressão no mesmo nível da linha anterior; Caso as regras acima venham a confundir o código ou espremê-lo contra a margem direita, apenas utilize a indentação de 8 espaços.
Aqui estão alguns exemplos de chamadas a métodos com linhas quebradas: funcao(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); variavel = funcao1(longExpression1, funcao2(longExpression2, longExpression3));
A seguir estão dois exemplos de quebra de uma expressão aritmética. A primeira é a preferida, desde que a quebra ocorra fora da expressão contida entre parênteses, que é de um nível elevado: longName1 = longName2 + (longName3 + longName4 - longName5) + 4 * longName6; // Preferida longName1 = longName2 + (longName3 + longName4 - longName5) + 4 * longName6; // Evitar
A seguir dois exemplos de métodos de indentação de declarações. O primeiro é o caso convencional. O segundo mudaria a 2ª e a 3ª linhas para a direita se for usada a indentação convencional. Ao invés disto identar apenas 8 espaços: //INDENTAÇÃO CONVENCIONAL someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } //INDENTAR 8 ESPAÇOS PARA EVITAR IDENTAÇÕES MUITO DISTANTES private static synchronized horkingLongMethodName (int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... }
Empacotamento de linhas para declarações "IF" devem geralmente usar a regra de 8 espaços, uma vez que a regra convencional (4 espaços) dificulta a visualização. Por exemplo: //NÃO USAR ESTA INDENTAÇÃO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //PESSIMO EMPACOTAMENTO doSomethingAboutIt(); //FACILITA PERDER A LINHA } //USAR ESTA INDENTAÇÃO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } //OU USAR ESTA INDENTAÇÃO if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); }
Aqui estão três formas aceitáveis de formatar expressões ternárias: alpha = (aLongBooleanExpression) ? beta : gama; alpha = (aLongBooleanExpression) ? beta : gama; alpha = (aLongBooleanExpression) ? beta : gama;
6. Comentários Os programas Java podem ter dois tipos de comentários: comentários de implementação e comentários de documentação. Comentários de implementação são aqueles encontrados em C++, delimitados por /*...*/, ou //. Comentários de documentação (também conhecidos como "doc comments") servem apenas para o Java e são delimitados por /**...*/. Comentários de documentação podem ser extraídos para HTML utilizando a ferramenta javadoc. Comentários de implementação são recursos para comentários a respeito do código ou de uma implementação particular. Comentários de documentação são usados para descrever a especificação do código, de uma perspectiva de livre implementação, a ser lida por desenvolvedores que não têm necessariamente que ter o código-fonte à mão. Comentários devem ser usados para dar uma visão geral do código e fornecer informação adicional, que não é facilmente disponível no próprio código. Comentários devem conter apenas informações relevantes para ler e entender o programa. Por exemplo, não devem ser incluídos como comentários informações sobre como o empacotamento correspondente é feito ou em qual diretório ele se encontra. Discussão sobre decisões de design não triviais ou não óbvias é apropriada, mas evite a duplicação de informação que está presente no código. É muito fácil comentários redundantes se desatualizarem. Em geral, evite alguns comentários que provavelmente se desatualizarão à medida que o código for se expandindo.
Obs: A freqüência de comentários às vezes reflete a qualidade pobre do código. Quando o programador se sentir compelido a adicionar comentários, deverá ser considerada a possibilidade de reescrever o código para deixá-lo mais claro. Comentários não devem ser fechados em grandes quadros desenhados com asteriscos ou outros caracteres. Comentários nunca devem incluir caracteres especiais como caractere de alimentação de formulário ou retorno de espaço.
6.1 For m ato s d e Com en tári o s d e Imp lem en tação Programas podem ter quatro estilos de comentários de implementação: De Bloco, Linha-Única, Em Trilha e Fim da Linha.
6.1.1 Com ent ário s d e Blo co Comentários de bloco são usados para prover descrições de arquivos, métodos, estruturas de dados e algoritmos. Comentários de bloco devem ser usados no início de cada arquivo e antes de cada método. Eles também podem ser usados em outros lugares, como dentro de métodos. Blocos de comentários dentro de uma função ou método devem ser identados no mesmo nível da descrição do código. Um bloco de comentário deve ser precedido por uma linha em branco para determinar a separação do resto do código. Blocos de comentários possuem um asterisco ―*‖ no início de cada linha exceto na primeira. Por exemplo: /* * Aqui esta um Bloco de Comentário. */
Blocos de comentários podem iniciar com /*-, que é reconhecido pelo identador(1) como um início de um bloco de comentário que não deve ser reformatado. Por exemplo: /** Este é um bloco de comentário com algumas formatações * muito especiais que eu quero identador(1) ignore. * * um * dois * três */
Obs: Se o identador(1) não for utilizado, não deve ser usada a combinação /*- no código nem devem ser feitas outras concessões, pois sempre há a possibilidade de outro programador utilizá-lo em seu código. Ver também o item ―6.2 Comentários de Documentação‖.
6.1.2 Com ent ário s d e Lin ha-Únic a Pequenos comentários podem aparecer em uma linha única identados no nível do código que segue. Se um comentário não pode ser escrito em uma linha única, deve ser seguido o formato do comentário em bloco (Ver item 6.1.1 Comentários de Bloco). Um comentário de linha única devem ser precedidos por uma linha em branco. Segue abaixo um exemplo de um comentário de linha única utilizando codificação Java: if
(condition) { /* Manipular a condição. */ ...
}
6.1.3 Co m ent ário s de Tril ha Pequenos comentários podem aparecer na mesma linha em que o código esta sendo descrito, mas devem ser deslocados longe o suficiente para separá-los das declarações. Se mais de um pequeno comentário aparecer em um pedaço de código, todos eles devem ser identados com o mesmo parâmetro de tabulação. Segue abaixo um exemplo de um comentário de linha única utilizando codificação Java: if (a == 2) { return TRUE; } else { return isprime(a); }
/* caso especial */ /* usa a condição a */
6.1.4 Com entário s de Final d e Li nh a O delimitador de comentário ―//‖ pode se referir a uma linha inteira ou pode
ser utilizado para continuação de uma linha anterior em uma nova linha (ou seja, comentar parte de uma linha). Não deve ser usado em múltiplas linhas consecutivas para textos de comentários; entretanto, pode ser usado em múltiplas linhas consecutivas para comentar seções de código. Segue abaixo exemplos utilizando estes três estilos utilizando a linguagem Java: if (foo > 1) { // Faça um duplo-flip. ... } else { return false; // Explicar o porque aqui. } //if (bar > 1) { // // // Faça um triplo-flip. // ... //} //else // return false;
6.2 Co m en tár io s d e Do c u m en ta ção
Obs: Ver o item ―12.1 – Exemplo de arquivo-fonte Java‖ para exemplos de formatos de comentários descritos aqui. Para maiores detalhes, ver ―How to Write Doc Comments for Javadoc‖ que inclui informação em tags de comentários de documentação (@return, @param, @see) no endereço abaixo: http://java.sun.com/products/jdk/javadoc/writingdoccomments.html Para maiores detalhes sobre comentários de documentação e javadoc, veja a página do javadoc em: http://java.sun.com/products/jdk/javadoc/ Comentários de documentação descrevem classes Java, interfaces, construtores, métodos e campos. Cada comentário de documentação é mantido dentro dos delimitadores de comentário /**...*/, com um comentário por API (Classe, interface, construtor, método ou campo). Esse comentário deve aparecer imediatamente antes da declaração. Por exemplo: /** * O exemplo de classe que provê ... */ class Exemplo { ...
Perceba que classes e interfaces não estão identadas, enquanto seus membros estão. A primeira linha do comentário de documentação (/**) para classes e interfaces não é identada; cada linha de comentário de documentação subseqüente possui um espaço de indentação (para verticalmente se alinhar aos asteriscos). Membros, incluindo construtores, possuem quatro espaços para a primeira linha de comentário de documentação e cinco espaços para as demais. Se for preciso dar informação sobre uma classe, interface, variável ou método que não é apropriado para documentação, deve ser utilizado um comentário de bloco (ver item 6.1.1) ou comentário de linha-única (ver item 6.1.2) imediatamente após a declaração. Por exemplo, detalhes sobre a implementação de uma classe devem ir em um tipo de comentário de bloco seguindo a declaração de classe e não no comentário de documentação da classe. Comentários de documentação não devem ser posicionados dentro de um bloco de definição de método ou de um construtor, porque Java associa comentários de documentação com a primeira declaração após o comentário.
7. Declarações 7.1 Núm ero p or Lin ha Uma declaração por linha é recomendada desde que a mesma incentiva a comentar. Em outras palavras, int nivel; // nível de indentação int tamanho; // tamanho da tabela
É preferível: int nivel, tamanho;
De forma alguma variáveis e funções devem ser declaradas na mesma linha. Por exemplo: long dbaddr, getDbaddr(); // ERRADO!
Também não podemos colocar diferentes tipos de dados na mesma linha. Por exemplo: int foo, fooarray[];
// ERRADO!
Obs: Os exemplos acima usam um espaço entre o tipo do dado e o identificador. Uma outra alternativa aceitável é a utilização de tabulação. Por exemplo: int nivel; // nível de indentação int tamanho; // tamanho da tabela Object entradaAtual; // entrada atual da tabela selecionada
7.2 L o c al iz ação Coloque as declarações apenas no início dos blocos. (Um bloco é qualquer código cercado por chaves ―{― e ―}‖.) Não espere para declarar variáveis até
a sua primeira utilização; isso pode confundir o programador descuidado e prejudicar a portabilidade do código dentro do escopo.
void meuMetodo() { int int1;
// início do bloco de método
if (condicao) { int int2; ... }
// início do bloco de “if”
}
Uma exceção para esta regra refere-se aos índices de loops do tipo ―for‖, nos quais o Java pode ser declarado na declaração ―for‖: for (int i = 0; i < maxLoops; i++) { ...
Evite declarações locais que ocultem declarações no nos níveis superiores. Por exemplo, não declare uma variável com o mesmo nome em um bloco interno: int count; ... func() { if (condicao) { int count; ... } ... }
//EVITAR!
7.3 In ic ial ização Tente inicializar variáveis locais onde elas são declaradas. A única razão para não inicializar uma variável onde elas são declaradas é se o valor inicial da mesma depender de algum processamento que necessite ocorrer primeiro.
7.4 Declar ações de Clas se e Inter fac e Quando codificando classes e interfaces Java, o seguinte formato de regras deve ser seguido:
Não colocar espaços entre o nome do método e os parênteses ―(― começando sua lista de parâmetros;
Chave de abertura ―{― deve aparecer no fim da mesma linha de comando
Chave de fechamento ―}‖ deve começar a linha identada para coincidir
da declaração; com a sua declaração de abertura correspondente, exceto quando uma declaração nula a chave ―}‖ deve aparecer imediatamente após a chave de abertura ―{―;
class Exemplo extends Object { int ivar1; int ivar2; Exemplo(int i, int j) { ivar1 = i; ivar2 = j; } int metodoVazio() {} ... }
Métodos devem ser separados por uma linha em branco.
8. Declarações / Comandos 8.1 Comando s Sim ples Cada linha deve conter no máximo um comando. Por exemplo: argv++; argc--; argv++; argc--;
// EVITAR! // CORRETO! // CORRETO!
Não use vírgula para agrupar múltiplos comandos a menos que seja por uma razão obvia. Por exemplo: if (err) { Format.print(System.out, “error”), exit(1); }
// ERRADO!
8.2 C o m a n d o s C o m p o s t o s Comandos compostos são comandos que contém listas de comandos encapsulados dentro de chaves ―{ comandos }‖. Ver os exemplos a seguir:
Os comandos encapsulados entre chaves devem ser identados um nível acima do comando composto; A chave de abertura deve estar no fim da linha que começa o comando composto; a chave de fechamento ―}‖ deve começar a linha e estar identado no começo do comando composto; Chaves são utilizadas em volta de todos os comandos, mesmo comandos simples, quando são parte de uma estrutura de controle, tanto quanto em comandos ―if -else‖ ou ―for‖. Isso torna mais fácil a adição de comandos
sem introduzir erros acidentalmente devido ao esquecimento da inclusão de chaves.
8.3 Comand o de Retorno (return) O comando return com um valor não deve usar parênteses a menos que torne o valor de retorno mais óbvio de alguma forma. Por exemplo: return; return meuDisco.size(); return (size ? size : defaultSize);
8.4 Comandos “if”, “if - else”, “if - else-if- else” A classe de comandos ―if -else‖ devem ter a seguinte forma: if (condicao) { comandos; } if (condicao) { comandos; } else { comandos; } if (condicao) { comandos; } else if (condicao) { comandos; } else if (condicao) { comandos; }
Obs: Comandos ―if‖ sempre usam chaves ―{}‖. Evite u tilizar a forma errada a seguir: if (condicao) comando;
// EVITAR! ESTE TIPO OMITE AS CHAVES {}!
8.5 Comandos “for” Um comando ―for‖ deve ter a seguinte forma: for (inicializacao; condicao; atualizacao) { comandos; }
Um comando ―for‖vazio (um em que todo o trabalho é feito nas cláusulas de
inicialização, de condição ou de atualização) deve ter a seguinte forma: for (inicializacao; condicao; atualizacao);
Quando usado a vírgula nas cláusulas de inicialização ou atualização de um comando ―for‖, evite a complexidade de utilizar mais de três variáveis. Se preciso, utilize comandos separados antes do loop ―for‖ (para cláusula de
inicialização) ou no final do loop (para cláusula de atualização).
8.6 Comandos “while” Um comando ―while‖ deve ter a seguinte forma: while (condicao) { comandos; }
Um comando ―while‖ em vazio deve ter a seguinte forma: while (condicao);
8.7 Comando “do- while” Um comando ―do-while‖ deve ter a seguinte forma: do { comandos; } while (condicao);
8.8 Comando “switch” Um comando ―switch‖ deve ter a seguinte forma:
switch(condicao) { case ABC: comandos; /* fallsthrough */ case DEF: comandos; break; case XYZ: comandos; break; default: comandos; break; }
Toda ocorrência de um caso ―falls through‖ (não incluir um comando ―br eak‖), deve ter adicionado um comentário onde o comando ―break‖
normalmente deveria estar. Isto é mostrado no exemplo acima com o comentário ―/* falls through */‖. Todo comando ―switch‖ deve incluir um caso padrão (default). O ―break‖ no
caso padrão é redundante, mas previne a entrada em uma situação de erro se posteriormente um novo caso for incluído.
8.9 Comando “try - catch” Um comando ―try-catch‖ deve ter o seguinte formato: try { comandos; } catch (ExceptionClass e) { comandos; }
9. Espaço em Branco 9.1 Linhas em B ranco Linhas em branco melhoram a leitura pela separação de seções de código que estão logicamente relacionadas. Duas linhas em branco devem sempre ser usadas nas seguintes circunstâncias:
Entre seções dos arquivos-fonte; Entre definições de classes e interfaces.
Uma linha em branco deve sempre ser usada nas seguintes circunstâncias: Entre métodos; Entre variáveis locais em um método e seu primeiro comando; Antes de um comentário de bloco (ver item 6.1.1) ou de linha-única (ver item 6.1.2); Entre seções lógicas dentro de um método para melhorar a leitura e entendimento.
9.2 Esp aços em B ranc o Espaços em branco devem ser usados nas seguintes circunstâncias:
Uma palavra-chave (keyword) seguida por parênteses deve ser separada por um espaço. Por exemplo: while (true) { ... }
Note que um espaço em branco não deve ser usado entre o nome do método e seu parênteses de abertura. Isso ajuda a distinguir palavraschave (keywords) de chamadas de método. Um espaço em branco deve aparecer após as vírgulas na lista de argumentos; Todos os operadores binários (exceto ―.‖) devem ser separados de seus
operandos por espaços. Espaços em branco nunca devem separar operadores ―únicos‖, como símbolo de subtração simples (―-―), de incremento (―++‖) ou de decréscimo (―—―) de seus operandos. Por
exemplo: a += c + d; a = (a + b) / (c * d); a += c + d; a = (a + b) / (c * d); while (d++ = s++) { n++; } prints(“size is “ + foo + “n”);
As expressões em um comando ―for‖ devem ser separadas por espaços
em branco. Por exemplo: for (expr1; expr2; expr3)
Casts devem ser seguidos por um espaço em branco. Por exemplo: meuMetodo((byte) aNum, (Object) x); minhaFuncao((int) (cp + 5), ((int) (i + 3)) + 1);
10. Convenções de Nomenclatura Convenções de Nomenclatura faz com que os programas fiquem mais fáceis de serem lidos. Eles podem também dar informação sobre a função ou o identificador – por exemplo, se é uma constante, pacote ou classe – que pode ser útil no entendimento do código.
Tipo de Identificador
Regras para Nomenclatura
Exemplos
Classes
Os nomes de classe devem ser class Imposto; substantivos, uma combinação class PesquisaImposto; de tamanhos de fonte (fontes maiúsculos e minúsculos) com a primeira letra em maiúsculo e as compostas também em maiúsculo, as demais seguem em minúsculo. Os nomes de classes devem, sempre que possível, ser simples e descritivos. Usar palavras completas – evitando acrônimos e abreviações (a menos que a abreviação seja a forma mais usada e conhecida do que a palavra longa, como URL ou HTML)
Pacotes
O prefixo de um pacote é com.sun.eng sempre escrito em letras com.apple.quicktime.v2 minúsculas em padrão ASCII edu.cmu.cs.bovik.cheese e deve ser um dos nomes de domínio de alto nível atualmente com, edu, gov, mil, net, org ou um dos códigos de duas letras em inglês que identifica os países de acordo com a especificação ―ISO Standard 3166, 1981‖.
Componentes subseqüentes do nome do pacote variam de acordo com a convenção interna da própria organização. Assim, convenções devem especificar que um certo nome de
diretório de componente é divisão, departamento, projeto, máquina ou login. Interfaces
Os nomes de interface devem seguir o mesmo padrão de nomenclatura dos nomes das classes.
interface ImpostoInterface; interface VeiculoInterface;
Métodos
Os métodos devem ser verbos, run(); com a primeira letra em runFast(); minúscula e a primeira letra getBackground(): das demais compostas em letra maiúscula.
Variáveis
Exceto para variáveis, todas as int instâncias, classes e classes char constantes se formam com a float primeira letra minúscula. As palavras compostas internas devem iniciar com letra maiúscula.
i; c; meuTamanho;
Nomes de variáveis devem ser pequenos mas com um significado. A escolha de um nome de variável deve ser mnemônico – ou seja, desenhado para indicar a intenção de seu uso. Os nomes de variáveis com apenas um caractere devem ser evitados, exceto nos casos de variáveis temporárias ―descartáveis‖. Os nomes mais usuais para variáveis temporárias são: i,j,k,m e n para inteiros; c,d, e e para caracteres. Constantes
Os nomes de variáveis constantes de classes declaradas e de constantes ANSI devem ser totalmente em letras maiúsculas com as palavras separadas por sublinhado (_). (As constantes ANSI devem ser evitadas para facilitar o debugging.).
static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1;
11. Práticas de Programação 11.1 Forn ecen do A ces s o àIns tânc ia e Vari áv eis de Cl ass e Não faça qualquer instância ou variável de classe publica sem ter uma boa razão. Muitas vezes, variáveis de instância não precisam ser explicitamente obtidas ou definidas – muitas vezes o que acontece como um efeito colateral de chamadas de método. Um exemplo de um apropriado uso de variáveis de instância públicas é o caso quando a classe é essencialmente uma estrutura de dados, sem comportamento próprio. Em outras palavras, se tivesse usado struct ao invés de uma class (se o Java suportasse struct), então seria apropriado fazer instâncias de variáveis públicas de classe.
11.2 Refer in d o -se a Var iáv eis d e Clas s e e Mé to d o s Evite usar um objeto para acessar uma variável de classe (static) ou método. Use um nome de classe ao invés disso. Por exemplo: classMethod(); //OK AClass.classMethod();
//OK
AnObject.classMethod();
//EVITAR!
11.3 Constantes Constantes numéricas (literais) não devem ser codificadas diretamente, exceto para – 1, 0 e 1, os quais podem aparecer como valores em contadores de loop do tipo ―for‖.
11.4 A tr ib u ições d e Var iáv eis Evite atribuir um valor para diversas variáveis em uma única instrução. Dificulta sua leitura. Por exemplo: fooBar.fChar = barFoo.lchar = „c‟;
// EVITAR!
Não use operadores de atribuição em um lugar onde pode ser facilmente confundido com um operador de igualdade. Por exemplo:
if (c++ = d++) { ... }
// EVITAR! Java não permite!
Deve ser escrito desta forma: if ((c++ = d++) != 0) { ... }
Não use atribuições embutidas em uma tentativa de melhorar a performance de execução do código. Isso é tarefa do job de compilação, e além disso, isso na verdade raramente ajuda. Por exemplo: d = (a = b + c) + r;
// EVITAR!
Deve ser escrito da seguinte forma: a = b + c; d = a + r;
11.5 Pr átic as Di v ers as 11.5.1 Par ên te s es Geralmente uma boa idéia o uso de parênteses livremente em expressões que envolvam operadores misturados para que sejam evitados problemas de precedência de operadores. Mesmo se a precedência do operador parecer clara, considerar que pode não ser para todos – não se pode assumir que todos os programadores tenham o mesmo nível de conhecimento e entendimento. if (a == b && c == d) // EVITAR! if ((a == b) && (c == d)) // CORRETO!
11.5.2 Valor es de Retor no Tente fazer com que a estrutura do programa se encaixe na intenção. Por exemplo: if (expressaoBoleana) { return TRUE; } else { return FALSE; }
Deve ser escrito como: return expressaoBoleana;
Da mesma forma que: if (condicao) { return x; } return y;
Deve ser escrito como: return (condição ? x : y);
11.5.3 Expressões antes de “?” no Operador Condicional Se uma expressão contendo um operador binário aparecer antes do sinal de interrogação (?) no ternário (?: operador), ele deveria ser usado entre parênteses. Por exemplo: (x >= 0) ? x : -x
11.5.4 Co m ent ário s Es pec iais Use XXX em um comentário para marcar algo que, mesmo contendo erros, funcione. Use FIXME para marcar algo que contenha erro e não funcione.
12. Exemplo de Código 12.1 Exem plo d e Códig o Fon te Java O seguinte exemplo mostra como formatar um código fonte Java contendo uma única classe pública. Interfaces são formatadas de forma similar. Para maiores informações, veja o item ―4.1.3 Declarações de Classe e de Interface‖ e ―6.2 Comentários de Documentação‖. /* * %W% %E% Firstname Lastname * * Copyright (c) 1993-1996 Sun Microsystems, Inc. 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. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. */ package java.blah; import java.blah.blahdy.BlahBlah; /** * Class description goes here. * * @version 1.10 04 Oct 1996 * @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; /** * ...method 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... } }
