Copyright (c) 1999 Scott Ambler, Ambysoft, Inc.

As Diretrizes de Codificação Java são fornecidas sob licença de Scott Ambler, Ambysoft Inc., www.ambysoft.com. Elas foram reformatadas para inclusão no Processo Unificado da Rational.

Conteúdo

1      Introdução
        1.1    A Primeira e Última Diretriz

2    Padrões de Codificação
      2.1    Convenções de Nomenclatura
      2.2    Convenções de Documentação
              2.2.1  Tipos de Comentários Java
              2.2.2  Um Visão Geral Rápida do javadoc   

3    Padrões para Funções-membro
      3.1    Nomeando Funções-membro
              3.1.1    Nomeando Funções-membro do Acessador
                         3.1.1.1    Getters
                         3.1.1.2    Setters
      3.2    Nomeando Construtores
      3.3    Visibilidade da Função-membro
      3.4    Documentando Funções-membro
               3.4.1    O Cabeçalho da Função-membro
               3.4.2    Documentação Interna
      3.5    Técnicas para Gravar Código Limpo
               3.5.1    Documente seu Código
               3.5.2    Utilize Parágrafo ou Recue seu Código
               3.5.3    Utilize Espaço em Branco em seu Código
               3.5.4    Siga a Regra dos 30 Segundos
               3.5.5    Grave Linhas de Comandos Simples e Curtas
               3.5.6    Especifique a Ordem das Operações

5    Padrões para Variáveis Locais
      5.1    Nomeando Variáveis Locais
                  5.1.1    Nomeando Fluxos
                   5.1.2    Nomeando Contadores de Loop
                   5.1.3    Nomeando Objetos de Exceção
        5.2   Declarando e Documentando Variáveis Locais
               5.2.1     Comentários Gerais sobre Declaração

6    Padrões para Parâmetros para Funções-membro
      6.1    Nomeando Parâmetros
      6.2    Documentando Parâmetros
               6.2.1    Utilize Interfaces para Tipos de Parâmetros

7    Padrões para Classes, Interfaces, Pacotes e Unidades de Compilação
      7.1    Padrões para Classes
                7.1.1    Nomeando Classes
                7.1.2    Documentando uma Classe
                7.1.3    Declarações de Classes
                7.1.4    Minimize a Interface Pública e Protegida
                            7.1.4.1    Defina Primeiro a Interface Pública
      7.2     Padrões para Interfaces
                7.2.1    Nomeando Interfaces
                            7.2.1.1    Alternativa
                7.2.2    Documentando Interfaces
      7.3     Padrões para Pacotes
                7.3.1    Nomeando Pacotes
                7.3.2    Documentando Pacotes
      7.4     Padrões para Unidades de Compilação
                7.4.1    Nomeando Unidades de Compilação
                7.4.2    Documentando Unidades de Compilação

8    Tratamento de Erros e Exceções

10    Padrões de Sucesso
       10.1    Utilizando esses Padrões com Eficácia
       10.2    Outros Fatores que Levam a Gravar Código com Sucesso

11    Resumo
        11.1    Convenções de Nomenclatura Java
        11.2    Convenções de Documentação Java
                   11.2.1    Tipos de Comentários Java
                   11.2.2    O que Documentar
        11.3    Convenções de Codificação Java (geral)

12    Referências

13    Glossário

1    Introdução

Este documento descreve a coleção de padrões, convenções e diretrizes para gravar código Java sólido. Elas são baseadas em princípios de engenharia de software comprovados e estáveis que levam a um código de fácil entendimento, manutenção e aprimoramento. Além disso, seguindo esses padrões de codificação, sua produtividade como desenvolvedor Java deve aumentar de maneira notável. A experiência mostra que tomar tempo para gravar código de alta qualidade logo do início, será muito mais fácil modificá-lo durante o processo de desenvolvimento. Finalmente, seguir um conjunto comum de padrões de codificação leva a maior consistência, tornando as equipes de desenvolvedores significativamente mais produtivas.

1.1    A Primeira e Última Diretriz 

Utilize o senso comum. Quando não for possível localizar uma regra ou diretriz, quando a regra não for aplicada de maneira óbvia ou quando todo o resto falhar: utilize o senso comum e verifique os princípios fundamentais. Essa regra substitui todas as outras. O senso comum é obrigatório.

2    Padrões de Codificação

Os padrões de codificação para Java são importantes porque levam a maior consistência dentro do código e com o código de seus colegas de trabalho. Maior consistência leva a código que é mais fácil de entender, o que significa ser mais fácil de desenvolver e manter. Isso reduz o custo geral dos aplicativos criados.

Você precisa se lembrar que seu código Java existirá por um longo tempo; bem depois que você tiver se deslocado para outros projetos. Uma meta importante durante o desenvolvimento é assegurar que seja possível transicionar seu trabalho para outro desenvolvedor ou para outra equipe de desenvolvedores, para que eles possam continuar a manter e aprimorar seu trabalho sem ter de investir um esforço excessivo para entender seu código. Um código que é difícil de entender corre o risco de ser jogado fora e reescrito.

2.1    Convenções de Nomenclatura

Discutiremos as convenções de nomenclatura em todos os padrões, portanto vamos montar a cena com alguns conceitos básicos:

1. Utilize descritores completos em inglês, que descrevam com precisão a variável, o campo e a classe; por exemplo, utilize nomes como firstName, grandTotal ou CorporateCustomer. Embora nomes como x1, y1 ou fn sejam fáceis de digitar porque são curtos, eles não fornecem nenhuma indicação do que representam, resultando em código difícil de entender, manter e aprimorar.
   
2. Utilize a terminologia aplicável ao domínio. Se os usuários referirem-se aos clientes como freguês, utilize o termo Customer para a classe, não Client. Muitos desenvolvedores cometem o engano de criar termos genéricos para conceitos, quando termos perfeitamente bons já existem no segmento de mercado ou domínio.
   
3. Utilize nomes compostos por letras maiúsculas e minúsculas para torná-los legíveis. Utilize letras minúsculas em geral, mas utilize maiúsculas para a primeira letra dos nomes das classes e interfaces, bem como a primeira letra de qualquer palavra não-inicial. [KAN97]
   
4. Utilize abreviações com moderação, mas se o fizer, utilize-as com inteligência. Isso significa que você deve manter uma lista de formas curtas padrão (abreviações), deve escolhê-las com sabedoria e deve utilizá-las de forma consistente. Por exemplo, se deseja utilizar uma forma curta para a palavra "number", utilize nbr, no ou num, documente qual foi a escolhida (na realidade não importa qual delas) e utilize apenas ela.
   
5. Evite nomes longos (< 15 caracteres é uma boa idéia). Embora o nome de classe PhysicalOrVirtualProductOrService possa parecer um bom nome de classe no momento, esse nome é simplesmente muito longo e você deve considerar renomeá-lo para algo mais curto, talvez algo como Offering.
   
6. Evite nomes semelhantes ou que sejam diferente apenas em maiúsculas e minúsculas. Por exemplo, os nomes de variáveis persistentObject e persistentObjects não devem ser utilizados em conjunto, e nem anSqlDatabase e anSQLDatabase.
   
7. Evite sublinhados de início ou encerramento. Nomes com sublinhados de início ou encerramento normalmente são reservados para finalidades do sistema e não devem ser utilizados para quaisquer nomes criados pelo usuário. Ainda mais importante, os sublinhados são maçantes e difíceis de se digitar, portanto tente evitar seu uso sempre que possível.

2.2    Convenções de Documentação

Também discutiremos convenções de documentação, portanto vamos discutir primeiro alguns dos conceitos básicos:

1. Os comentários devem aumentar a clareza do código. A razão pela qual você documenta seu código é torná-lo mais compreensível para você, seus colegas de trabalho e qualquer outro desenvolvedor que venha depois de você.
   
2. Se não valer a pena documentar seu programa, provavelmente não vale a pena executá-lo. [NAG95]
   
3. Evite decoração; isto é, não utilize comentários do tipo banner. Nos anos 60 e 70, os programadores COBOL criaram o hábito de desenhar caixas, normalmente com asteriscos, em torno de seus comentários internos. Claro que isso lhes deu uma vazão para seus anseios artísticos, mas francamente era uma grande perda de tempo que adicionava pouco valor ao produto final. Você deseja gravar código limpo, não bonito. Além disso, como muitas das fontes utilizadas para exibir e imprimir seu código são proporcionais e muitas não são, de qualquer modo não é possível alinhar as caixas corretamente.
   
4. Mantenha os comentários simples. Alguns dos melhores comentários são notas simples em formato de indicação. Você não precisa escrever um livro; precisa apenas fornecer informações suficientes para que outros possam entender o código.
   
5. Escreva a documentação antes de escrever o código. A melhor forma de documentar o código é escrever os comentários antes de escrever o código. Isso lhe dá uma oportunidade de pensar sobre como o código funcionará antes de escrevê-lo e assegurará que a documentação será escrita. De forma alternativa, você deve pelo menos documentar seu código à medida que o escreve. Como a documentação torna o código mais fácil de entender, é possível aproveitar esse fato enquanto o está desenvolvendo. Você investirá o tempo escrevendo a documentação, portanto deverá pelo menos obter algo dela. [AMB98]
   
6. Documente porque algo está sendo feito, não apenas o que. Por exemplo, o código no Exemplo 1 a seguir mostra que um desconto de 5% está sendo concedido em pedidos de de US$1.000 ou mais. Por que isso está sendo feito? Existe uma regra de negócios que indique que os pedidos grandes tenham um desconto? Existe alguma promoção por tempo limitado para pedidos grandes ou é um programa permanente? O programador original estava apenas sendo generoso? Você não sabe a menos que esteja documentado em algum lugar, seja no próprio código fonte ou em um documento externo.

Exemplo 1:

if ( grandTotal >= 1000.00)

{

grandTotal = grandTotal * 0.95;

}

2.2.1    Tipos de Comentários Java

Java tem três estilos de comentários: 

• comentários de documentação que iniciam com /** e terminam com */
• comentários no estilo C que iniciam com /* e terminam com */
• comentários de linha única que iniciam com // e vão até o final da linha do código fonte

O gráfico a seguir é um resumo de um uso sugerido para cada tipo de comentário, bem como diversos exemplos.

Tipo de Comentário	Uso	Exemplo
Documentação	Utilize comentários de documentação imediatamente antes de declarações de interfaces, classes, funções-membro e campos para documentá-los. Os comentários de documentação são processados pelo javadoc (consulte a seguir) para criar documentação externa para uma classe.	/** Customer: A customer is any person or organization that we sell services and products to. @author S.W. Ambler */
Estilo C	Utilize comentários em estilo C para documentar linhas de código que não mais são aplicáveis, mas que deseja manter para o caso dos usuários mudarem de idéia, ou porque deseja desativá-las temporariamente durante a depuração.	/* This code was commented out by B. Gustafsson on June 4, 1999 because it was replaced by the preceding code. Delete it after two years if it is still not applicable. . . . (the source code ) */
Linha única	Utilize os comentários de linha única internamente nas funções-membro para documentar a lógica de negócios, seções de código e declarações de variáveis temporárias.	// Apply a 5% discount to all // Invoices Over $1000 Due To // generosity campaign started in // Feb. of 1995.

O fato importante é que sua organização deve definir um padrão de como os comentários em estilo C e comentários de única linha deverão ser utilizados e, posteriormente, seguir esse padrão de forma consistente. Utilize um tipo para documentar a lógica de negócios e o outro para documentar código antigo retirado. Utilize comentários de linha única para lógica de negócios porque pode colocar a documentação na mesma linha que o código (isso é chamado inlining). Utilize comentários do estilo C para documentar código antigo retirado porque isso permite comentar várias linhas de uma só vez. Como o estilo C é muito semelhante a comentários de documentação, para evitar confusão, não os utilize em nenhum outro lugar.

Cuidado com Comentários de Final de Linha-[MCO93] argumenta fortemente contra a utilização de comentários seqüenciais, também conhecidos como comentários de final de linha. McConnell aponta que os comentários devem ser alinhados à direita do código para que não interfiram com a estrutura visual do código. Como resultado, eles tendem a ser difíceis de formatar e "se você utilizar muitos deles, é demorado alinhá-los. Tal tempo não é gasto no aprendizado adicional sobre o código; ele é dedicado somente à tediosa tarefa de pressionar a barra de espaço ou a tecla Tab." Também aponta que os comentários de final de linha são difíceis de se manter porque quando o código na linha cresce, ele empurra o comentário de final de linha e, se você os estiver alinhando, deverá fazer o mesmo para o restante deles.

2.2.2        Uma Visão Geral Rápida do javadoc

No JDK (Java Development Kit) da Sun está incluído um programa denominado javadoc que processa arquivos de código Java e produz documentação externa, no formato de arquivos HTML, para seus programas Java. O Javadoc suporta um número limitado de tags; as palavras reservadas que marcam o início de uma seção de documentação. Consulte a documentação do JDK javadoc para obter detalhes adicionais.

Tag	Utilizada para	Objetivo
@author name	Classes, Interfaces	Indica o(s) autor(es) de um determinado trecho de código. Deve ser utilizada uma tag por autor.
@deprecated	Classes, Funções-membro	Indica que a API para a classe foi desaprovada e, portanto, não mais deve ser utilizada.
@exception name description	Funções-membro	Descreve as exceções emitidas por uma função-membro. Você deve utilizar uma tag por exceção e fornecer o nome completo da classe à exceção.
@param name description	Funções-membro	Utilizada para descrever um parâmetro transmitido para uma função-membro, incluindo seu tipo ou classe e seu uso. Utilize uma tag por parâmetro.
@return description	Funções-membro	Descreve o valor de retorno, se houver, de uma função-membro. Você deve indicar o tipo ou classe e o(s) uso(s) potencial(is) do valor de retorno.
@since	Classes, Funções-membro	Indica por quanto tempo o item existiu; isto é, desde o JDK 1.1.
@see ClassName	Classes, Interfaces, Funções-membro, Campos	Gera um link de hipertexto na documentação para a classe especificada. É possível, e provavelmente necessário, utilizar um nome de classe completo.
@see ClassName#member functionName	Classes, Interfaces, Funções-membro, Campos	Gera um link de hipertexto na documentação para a função-membro especificada. É possível, e provavelmente necessário, utilizar um nome de classe completo.
@version text	Classes, Interfaces	Indica as informações sobre a versão para um determinado trecho de código.

A forma que o código é documentado tem um grande impacto, tanto em sua própria produtividade quanto na produtividade de qualquer outra pessoa que o mantenha e aprimore posteriormente. Documentando seu código no início do processo de desenvolvimento, você fica mais produtivo porque isso o força a pensar diretamente na lógica antes de confirmá-la no código. Além do mais, quando revisitar o código escrito dias ou semanas antes, poderá facilmente determinar o que você estava pensando quando o escreveu porque isso já está documentado para você.

3    Padrões para Funções-membro

Nunca se esqueça de que o código escrito hoje, ainda poderá ser utilizado muitos anos à frente, e provavelmente será mantido e aprimorado por outra pessoa. Você deve se esforçar para manter o código tão "limpo" e compreensível quanto possível, porque esses fatores tornam mais fácil manter e aprimorá-lo.

3.1    Nomeando Funções-membro

As funções-membro devem ser nomeadas utilizando-se uma descrição completa em inglês, utilizando nomes compostos por letras maiúsculas e minúsculas com a primeira letra de cada palavra não-inicial em maiúsculas. Também é uma prática comum que a primeira palavra do nome de uma função-membro seja um verbo forte e ativo.

Exemplos:

openAccount()

printMailingLabel()

save()

delete()

Essa convenção resulta em funções-membro cujo objetivo pode normalmente ser determinado apenas examinando-se seus nomes. Embora essa convenção resulte em um pouco mais de digitação pelo desenvolvedor porque ela normalmente resulta em nomes longos, isso mais que compensa pela capacidade aumentada de compreensão do código.

3.1.1    Nomeando Funções-membro do Acessador

Discutiremos os acessadores, funções-membro que obtêm e definem os valores dos campos (campos ou propriedades), em maiores detalhes em um próximo capítulo. As convenções de nomenclatura para acessadores, entretanto, são resumidas a seguir.

3.1.1.1    Getters 

Getters são funções-membro que retornam o valor de um campo. Você deve prefixar a palavra "get" no nome do campo, a menos que ele seja um campo booleano, quando você deve prefixar "is" no nome do campo em vez de "get".

Exemplos:

getFirstName()

getAccountNumber()

isPersistent()

isAtEnd()

Seguindo essa convenção de nomenclatura, você torna óbvio que uma função-membro retorna um campo de um objeto, e para getters booleanos, você torna óbvio que ela retorna true ou false. Outra vantagem desse padrão é que ele segue as convenções de nomenclatura utilizadas pelo BDK (Beans Development Kit) para funções-membro getter. [DES97] A principal desvantagem é que "get" é supérfluo e requer digitação adicional.

Uma alternativa viável, com base em convenções corretas em inglês, é utilizar o prefixo "has" ou "can" em vez de "is" para getters Booleanos. Por exemplo, nomes de getter tais como hasDependents() e canPrint() fazem muito sentido ao ler o código. O problema com essa abordagem é que o BDK não encontrará essa estratégia de nomenclatura (ainda). É possível renomear essas funções-membro como isBurdenedWithDependents() e isPrintable().

3.1.1.2    Setters

Os setters, também conhecidos como modificadores, são funções-membro que modificam os valores de um campo. Você deve prefixar a palavra "set" no nome do campo, independentemente do tipo de campo.

Exemplos:

setFirstName(String aName)

setAccountNumber(int anAccountNumber)

setReasonableGoals(Vector newGoals)

setPersistent(boolean isPersistent)

setAtEnd(boolean isAtEnd)

Seguindo essa convenção de nomenclatura, você torna óbvio que uma função-membro define o valor de um campo de um objeto. Outra vantagem desse padrão é que ele segue as convenções de nomenclatura utilizadas pelo BDK para funções-membro setter. [DES97] A principal desvantagem é que "set" é supérfluo e requer digitação adicional.

3.2    Nomeando Construtores

Customer()

SavingsAccount()

PersistenceBroker()

3.3    Visibilidade da Função-membro

Para um bom design onde o acoplamento entre classes seja minimizado, o método baseado na experiência geral é ser tão restritivo quanto possível ao definir a visibilidade de uma função-membro. Se uma função-membro não precisar ser pública, torne-a protegida e, se não precisar ser protegida, torne-a privada.

Visibilidade	Descrição	Uso Correto
public	Uma função-membro pública pode ser acessada por qualquer outra função-membro em qualquer outro objeto ou classe.	Quando a função-membro deve ser acessível por outros objetos e classes fora da hierarquia de classe em que a função-membro está definida.
protected	Uma função-membro protegida pode ser chamada por qualquer função-membro na classe em que ela está definida, quaisquer subclasses dessa classe ou quaisquer classes no mesmo pacote.	Quando a função-membro fornece o comportamento necessário internamente na hierarquia de classe ou pacote, mas não externamente.
private	Uma função-membro privada pode ser chamada apenas por outras funções-membro na classe em que ela está definida, mas não nas subclasses.	Quando a função-membro fornece o comportamento específico para a classe. As funções-membro privadas normalmente são o resultado da recriação, também conhecida como reorganização, do comportamento das demais funções-membro dentro da classe para encapsular um comportamento específico.
default	Por padrão (nenhuma visibilidade especificada, uma função pode ser chamada apenas por outras funções-membro na classe em que ela está definida ou em quaisquer classes no mesmo pacote.	Quando a função-membro fornece o comportamento necessário pelas classes no mesmo pacote, mas não externamente, e não pelas subclasses.

3.4    Documentando Funções-membro

3.4.1    O Cabeçalho da Função-membro

Toda função-membro Java deve incluir algum tipo de cabeçalho, denominado documentação da função-membro, no início da página do código fonte, que documente todas as informações críticas para compreendê-lo. Essas informações incluem, mas não estão limitadas a, o seguinte:

1. O que e porque a função-membro faz o que faz. Documentando o que uma função-membro faz, você facilita que outros determinem se podem reutilizar seu código. A documentação do porque ela faz algo facilita que terceiros coloquem seu código no contexto. Também facilita que outros determinem se uma nova alteração deve ou não realmente ser feita em um trecho de código (talvez a razão para a nova alteração entre em conflito com a razão pela qual o código foi escrito a princípio).
   
2. Qual função-membro deve ser transmitida como parâmetro. Também é necessário indicar quais parâmetros, se houver, devem ser transmitidos para uma função-membro e como serão utilizados. Essa informação é necessária para que outros programadores saibam quais informações devem ser transmitidas para uma função-membro. A tag @param do javadoc, discutida na seção 2.2.2, Uma Visão Geral Rápida do javadoc, é utilizada para isso.
   
3. O que uma função-membro retorna. É necessário documentar o que, se for o caso, uma função-membro retorna, para que outros programadores possam utilizar o valor ou objeto de retorno de forma apropriada. A tag @return do javadoc, discutida na seção 2.2.2, Uma Visão Geral Rápida do javadoc, é utilizada para isso.
   
4. Erros conhecidos. Quaisquer problemas importantes com uma função-membro devem ser documentados para que outros desenvolvedores entendam a fragilidade e as dificuldades com a função-membro. Se um determinado erro for aplicável a mais de uma função-membro dentro de uma classe, em vez disso ele deve ser documentado para a classe.
   
5. Todas as exceções emitidas por uma função-membro. É necessário documentar todas e quaisquer exceções que uma função-membro emita, para que outros programadores saibam o que seu código precisa capturar. A tag @exception do javadoc, discutida na seção 2.2.2, Uma Visão Geral Rápida do javadoc, é utilizada para isso.
   
6. Decisões de visibilidade. Se você acreditar que sua opção de visibilidade para uma função-membro será questionada por outros desenvolvedores - talvez você tenha tornado pública uma função-membro, embora ainda nenhum outro objeto chame a função-membro - deverá documentar sua decisão. Isso ajudará a tornar claro seu pensamento para outros desenvolvedores, para que eles não gastem tempo se preocupando por quê você fez algo questionável.
   
7. Como uma função-membro altera o objeto. Se uma função-membro alterar um objeto, por exemplo, a função-membro withdraw() de uma conta bancária modificar o saldo da conta, isso precisa ser indicado. Essa informação é necessária para que outros programadores Java saibam exatamente como uma chamada de função-membro afetará o objeto de destino.
   
8. Evite a utilização de cabeçalhos que contenham informações como autor, números de telefone, datas de criação e modificação e local da unidade (ou nome do arquivo), porque essas informações rapidamente se tornam obsoletas. Coloque avisos de direitos autorais de direito à propriedade no final da unidade. Por exemplo, os leitores não desejam precisar rolar por duas ou três páginas de texto que não seja útil para a compreensão do programa, nem desejam rolar por texto que não contenha nenhuma informação do programa, tais como um aviso de direitos autorais. Evite a utilização de barras verticais ou caixas ou quadros fechados, que apenas adicionam ruído visual e são difíceis de se manter consistentes. Utilize uma ferramenta de gerenciamento de configuração para manter o histórico da unidade.
   
9. Exemplos de como chamar a função-membro, se apropriado. Uma das formas mais fáceis de determinar como um trecho de código funciona é consultar um exemplo. Considere a inclusão de um exemplo ou dois sobre como chamar uma função-membro.
   
10. Condições prévias e posteriores aplicáveis. Uma condição prévia é uma restrição sob a qual uma função-membro funcionará corretamente e uma condição posterior é uma propriedade ou asserção que será verdadeira depois que a execução de uma função-membro for concluída. [MEY88] De muitas formas as condições prévias e posteriores descrevem as premissas feitas ao gravar uma função-membro [AMB98], definindo exatamente os limites de como uma função-membro é utilizada.
    
11. Todos os problemas de simultaneidade. A simultaneidade é um conceito novo e complexo para muitos desenvolvedores e, na realidade, no máximo, é um tópico antigo e complexo para programadores de simultaneidade experientes. O resultado final é que se você utilizar os recursos de programação simultânea do Java, deverá documentá-los completamente. O [LEA97] sugere que quando uma classe incluir funções-membro sincronizadas e não-sincronizadas, é necessário documentar o contexto de execução do qual uma função-membro depende, especialmente quando requerer acesso irrestrito, para que outros desenvolvedores possam utilizar suas funções-membro com segurança. Quando um definidor, uma função-membro que atualiza um campo, de uma classe que implementa a interface Runnable não está sincronizado, é necessário documentar a(s) razão(ões) para isso. Finalmente, se você substituir ou sobrecarregar uma função-membro e alterar sua sincronização, também deverá documentar o motivo.
    
12. Você deve documentar algo apenas quando isso ajuda a clarificar seu código. Você não documentaria todos os fatores descritos anteriormente para toda e qualquer função-membro, porque nem todos os fatores são aplicáveis a todas as funções-membro. Você deve, entretanto, documentar vários deles para cada função-membro gravada.

3.4.2    Documentação Interna

3.5    Técnicas para Gravar Código Limpo

3.5.1    Documente seu Código 

3.5.2    Utilize Parágrafo ou Recue seu Código 

3.5.3    Utilize Espaço em Branco em seu Código 

Algumas linhas em branco, chamadas de espaço em branco, incluídas no código Java podem ajudar a torná-lo muito mais legível dividindo-o em seções pequenas e fáceis de entender. O [VIS96] sugere a utilização de uma única linha em branco para separar grupos lógicos de código, tais como estruturas de controle e duas linhas em branco para separar definições de função-membro. Sem espaço em branco, é muito difícil ler e entender.

3.5.4    Siga a Regra dos 30 Segundos 

3.5.5    Grave Linhas de Comandos Simples e Curtas 

3.5.6    Especifique a Ordem das Operações 

4    Padrões para Campos e Propriedades

4.1    Nomeando Campos

Você deve utilizar um descritor completo em inglês para nomear os campos, [GOS96] e [AMB98], dessa forma tornando óbvio o que o campo representa. Os campos que são coleções, como matrizes ou vetores, devem receber nomes no plural para indicar que eles representam vários valores.

Exemplos:

4.1.1    Nomeando Componentes (widgets)

Para nomes de componentes (widgets de interface), você deve utilizar um descritor completo em inglês, acrescentando como sufixo o tipo do widget. Isso facilita a identificação do objetivo do componente, bem como seu tipo, o que facilita a localização de cada componente em uma lista. Muitos ambientes de programação visual fornecem listas de todos os componentes em um applet ou aplicativo e isso pode ser confuso quando tudo está nomeado como button1, button2 e assim por diante.

Exemplos:

4.1.1.1    Alternativa para Nomenclatura de Componentes: Notação Húngara 

A "Notação Húngara" [MCO93] tem como base o princípio de que um campo deve ser nomeado utilizando a seguinte abordagem: xEeeeeeEeeeee em que x indica o tipo do componente e EeeeeEeeeee é o descritor completo em inglês.

Exemplos:

A principal vantagem é que isso é um padrão de mercado comum para código C++, portanto muitas pessoal já o seguem. A partir do nome da variável, os desenvolvedores podem julgar rapidamente seu tipo e como ela é utilizada. As principais desvantagens são que a notação de prefixo se torna

4.1.1.2   Alternativa para Nomenclatura de Componentes: Notação Húngara com Sufixo 

Basicamente, essa é uma combinação das outras duas alternativas e resulta em nomes como okPb, customerLb, fileM e newFileMi. A principal vantagem é que o nome do componente indica o tipo do widget e que widgets do mesmo tipo não são agrupados em uma lista alfabética. A principal desvantagem é que você ainda não está utilizando uma descrição completa em inglês, tornando o padrão mais difícil de lembrar, porque ele se desvia da norma.

4.1.1.3    Definir Padrões de Nome de Componente 

Seja qual for a convenção escolhida, você desejará criar uma lista de nomes de widget "oficiais". Por exemplo, ao nomear botões, você utiliza Button, PushButton, b ou pb? Crie uma lista e disponibilize-a para todos os desenvolvedores Java em sua organização

4.1.2    Nomeando Constantes

Quando os campos forem declarados como protegidos, existe a possibilidade de que as funções-membro em subclasses os acessem diretamente, aumentando eficazmente o acoplamento dentro de uma hierarquia de classe. Isso torna as classes mais difíceis de se manter e aprimorar e, portanto, deve ser evitado. Os campos nunca devem ser acessados diretamente; em vez disso, deve-se utilizar funções-membro do acessador (consulte a seguir).

Visibilidade	Descrição	Uso Correto
public	Um campo público pode ser acessado por qualquer outra função-membro em qualquer outro objeto ou classe.	Não torne os campos públicos.
protected	Um campo protegido pode ser acessado por qualquer função-membro na classe em que ele está declarado ou por quaisquer funções-membro definidas nas subclasses dessa classe.	Não torne os campos protegidos.
private	Um campo privado pode ser acessado apenas por funções-membro na classe em que ele está declarado, mas não nas subclasses.	Todos os campos devem ser privados e devem ser acessados por funções-membro getter e setter (acessadores).

Para campos que não são persistentes (eles não serão salvos no armazenamento permanente), você deve marcá-los como estáticos ou transientes [DES97]. Isso faz com que eles estejam em conformidade com as convenções do BDK.

4.2.1    Não "Oculte" Nomes 

"Um bom design de programa procura isolar partes de um programa de influências externas desnecessárias, não pretendidas ou de outra forma não desejadas. Os modificadores de acesso (acessadores) fornecem um meio explícito e verificável para que a linguagem controle tais contatos." [KAN97]

As funções-membro do acessador aprimoram a capacidade de manutenção das classes das seguintes maneiras:

1. Atualizando campos. Você tem pontos únicos de atualização para cada campo, facilitando a modificação e o teste. Em outras palavras, os campos são encapsulados.
   
2. Obtendo os valores de campos. Você tem controle completo sobre como os campos são acessados e por quem.
   
3. Obtendo os valores de constantes e os nomes das classes. Encapsulando o valor de constantes e nomes de classe em funções-membro getter quando esses valores/nomes forem alterados, é necessário apenas atualizar o valor no getter e não em cada linha de código em que a constante/nome é utilizada.
   
4. Inicializando campos. A utilização de inicialização adiada assegura que os campos sempre sejam inicializados e que o sejam apenas se forem necessários.
   
5. Reduzindo o acoplamento entre uma subclasse e sua(s) superclasse(s). Quando as subclasses acessarem campos herdados apenas utilizando suas funções-membro de acessador correspondentes, isso possibilita alterar a implementação dos campos na superclasse sem afetar nenhuma de suas subclasses, efetivamente reduzindo o acoplamento entre elas. Os acessadores reduzem o risco da "classe-base frágil" em que as alterações em uma superclasse se estendem pelas suas subclasses.
   
6. Encapsulando alterações em campos. Se as regras de negócios pertencentes a um ou mais campos forem alteradas, você pode potencialmente modificar os acessadores para fornecer a mesma habilidade anterior à alteração, facilitando a resposta para as novas regras de negócios.
   
7. Simplificando problemas de simultaneidade. O [LEA97] aponta que funções-membro setter fornecem um único local para incluir notifyAll se tiver waits com base no valor desse campo. Isso torna a transição para uma solução simultânea muito mais fácil.
   
8. A ocultação de nomes se torna menos que um problema. Embora você deva evitar a ocultação de nomes, dar às variáveis locais o mesmo nome que os campos, a utilização de acessadores para sempre acessar campos significa que é possível dar às variáveis locais qualquer nome desejado. Não é necessário se preocupar sobre a ocultação de nomes de campos porque de qualquer maneira nunca as acessará diretamente.

4.4.1.1    Quando Não Utilizar Acessadores 

O único momento em que você pode desejar não utilizar acessadores é quando o tempo de execução for de máxima importância. No entanto, é um caso muito raro em que o aumento de acoplamentos em seu aplicativo justifica essa ação.

As funções-membro getter devem receber o nome "get" + nome do campo, a menos que o campo represente um Booleano (verdadeiro ou falso), caso no qual o getter receberá o nome "is" + nome do campo. As funções-membro setter devem receber o nome "set" + nome do campo, independentemente do tipo do campo ([GOS96] e [DES97]). Note que o nome do campo é sempre composto por letras maiúsculas e minúsculas com a primeira letra de todas as palavras em maiúsculas. Essa convenção de nomenclatura é utilizada de forma consistente no JDK e é requerida para o desenvolvimento de beans.

Exemplos:

Campo	Tipo	Nome do Getter	Nome do Setter
firstName	string	getFirstName()	setFirstName()
address	Address object	getAddress()	setAddress()
persistent	boolean	isPersistent()	setPersistent()
customerNo	int	getCustomerNo()	setCustomerNo()
orderItems	Array of OrderItem objects	getOrderItems()	setOrderItems()

4.4.3    Técnicas Avançadas para Acessadores

Os acessadores podem ser utilizados para mais que apenas obter e definir os valores de campos da instância. Esta seção discute como aumentar a flexibilidade do seu código pela utilização de acessadores para:

• inicializar os valores de campos
• acessar valores constantes
• acessar coleções
• acessar diversos campos simultaneamente

4.4.3.1    Inicialização Adiada 

As variáveis precisam ser inicializadas antes de serem acessadas. Existem duas escolas de pensamento para a inicialização: Inicializar todas as variáveis no momento em que o objeto é criado (a abordagem tradicional) ou inicializar no momento de sua primeira utilização. 

A primeira abordagem utiliza funções-membro especiais que são chamadas quando o objeto é criado pela primeira vez, chamadas construtores. Embora isso funcione, normalmente prova ser propenso a erros. Ao incluir uma nova variável, você pode facilmente esquecer de atualizar os construtores.

Uma abordagem alternativa é denominada inicialização adiada, em que os campos são inicializados por suas funções-membro getter, como mostrado a seguir. Note como uma função-membro setter é utilizada dentro da função-membro getter. Note que a função-membro verifica se o número da filial é zero; ser for, ela a define para o valor padrão apropriado.

O objetivo principal dos acessadores é encapsular o acesso aos campos para reduzir o acoplamento no código. As coleções, tais como matrizes e vetores, como são mais complexas que campos de valor único, naturalmente precisam ter mais do que apenas as funções-membro getter e setter padrão implementadas para elas. Especificamente, como é possível incluir e remover de coleções, as funções-membro de acessador precisam ser incluídas para fazê-lo. Inclua as seguintes funções-membro do acessador onde apropriado para um campo que seja uma coleção:

Tipo da Função-membro	Convenção de nomenclatura	Exemplo
Getter para a coleção	getCollection()	getOrderItems()
Setter para a coleção	setCollection()	setOrderItems()
Inserir um objeto na coleção	insertObject()	insertOrderItem()
Excluir um objeto da coleção	deleteObject()	deleteOrderItem()
Criar e incluir um novo objeto na coleção	newObject()	newOrderItem()

A vantagem dessa abordagem é que a coleção é totalmente encapsulada, permitindo substituí-la posteriormente por outra estrutura, talvez uma lista vinculada ou uma árvore-B.

4.4.3.4   Acessando Vários Campos Simultaneamente

/** Set the position of the shape */

protected void setPosition(Float x, Float y)

{

	setXPosition(x);

	setYPosition(y);

}

/** Set the x position.  Important: Invoke setPosition(), not this member function. */

private void setXPosition(Float x)

{

	xPosition = x;

}

/** Set the y position of the shape

    Important: Invoke setPosition(), not this member function.

*/

private void setYPosition(Float y)

{

	yPosition = y;

}

4.5    Visibilidade dos Acessadores

4.6    Sempre Inicialize Campos Estáticos

5    Padrões para Variáveis Locais

5.1    Nomeando Variáveis Locais

Em geral, as variáveis locais são nomeadas seguindo as mesmas convenções utilizadas para campos; em outras palavras, utilize descritores completos em inglês com a primeira letra de qualquer palavra não-inicial em maiúsculas.

Pelo bem da conveniência, entretanto, essa convenção de nomenclatura é relaxada para vários tipos específicos de variáveis locais:

• Fluxos
• Contadores de loop
• Objetos de exceção

5.1.1    Nomeando Fluxos

5.1.2    Nomeando Contadores de Loop

5.1.3    Nomeando Objetos de Exceção

5.2    Declarando e Documentando Variáveis Locais

5.2.1    Comentários Gerais sobre Declaração

6    Padrões para Parâmetros para Funções-membro

6.1    Nomeando Parâmetros

Os parâmetros devem ser nomeados seguindo as mesmas convenções utilizadas para variáveis locais. Da mesma forma que as variáveis locais, a ocultação do nome é um problema.

Exemplos:

customer

inventoryItem

photonTorpedo

e

Uma alternativa viável, obtida do Smalltalk, é utilizar as convenções de nomenclatura para variáveis locais, com a inclusão de "a" ou "an" na frente do nome. Incluir "a" ou "an" ajuda a tornar o parâmetro destacado de campos e variáveis locais, evitando o problema de ocultação de nome. Essa é a abordagem preferida.

Exemplos:

aCustomer

anInventoryItem

aPhotonTorpedo

anInputStream

anException

6.2    Documentando Parâmetros

Os parâmetros de uma função-membro são documentados na documentação de cabeçalho da função-membro utilizando a tag @param do javadoc. Você deve descrever o seguinte:

1. Para que ele deve ser utilizado. É necessário documentar para que um parâmetro é utilizado, a fim de que outros desenvolvedores entendam o contexto completo de como o parâmetro será utilizado.
   
2. Quaisquer restrições ou condições prévias. Se o intervalo completo de valores de um parâmetro não for aceitável para uma função-membro, o responsável pela chamada dessa função-membro precisa saber. Talvez uma função-membro aceite apenas números positivos ou cadeias com menos de cinco caracteres.
   
3. Exemplos. Se não for totalmente óbvio o que deve ser um parâmetro, será necessário fornecer um ou mais exemplos na documentação.

6.2.1    Utilize Interfaces para Tipos de Parâmetros

Em vez de especificar uma classe, como um Object, para o tipo de um parâmetro, se apropriado especifique uma interface, tal como Runnable. A vantagem é que essa abordagem, dependendo da situação, pode ser mais específica (Runnable é mais específico que Object) ou potencialmente pode ser uma melhor forma de suportar polimorfismo. Em vez de insistir que um parâmetro seja uma instância de uma classe em uma hierarquia de classes específica, especifique que ela suporta uma interface específica implicando que ela precisa apenas estar em conformidade de modo polimórfico ao que você precisa.

7    Padrões para Classes, Interfaces, Pacotes e Unidades de Compilação

7.1    Padrões para Classes

Os padrões importantes para classes têm como base:

• convenções de nomenclatura
• convenções de documentação
• convenções de declaração
• a interface pública e protegida

7.1.1    Nomeando Classes

A convenção padrão do Java utiliza um descritor completo em inglês, iniciando com a primeira letra em maiúscula e utilizando um nome composto por letras maiúsculas e minúsculas para o resto. ([GOS96] e [AMB98])

Os nomes de classes devem estar na forma singular.

Exemplos:

Um dos princípios do design orientado a objetos é minimizar a interface pública de uma classe. Há várias razões para isso:

1. Facilidade de aprendizado. Para aprender como utilizar uma classe, você deve entender apenas sua interface pública. Quanto menor for a interface pública, mais fácil será aprender uma classe.
   
2. Acoplamento reduzido. Sempre que a instância de uma classe enviar uma mensagem para uma instância de outra classe, ou diretamente para a própria classe, as duas classes se tornam acopladas. Minimizar a interface pública implica na minimização das oportunidades de acoplamento.
   
3. Maior flexibilidade. Isso está diretamente relacionado ao acoplamento. Sempre que desejar alterar a forma que uma função-membro em sua interface pública é implementada - talvez você queira modificar o que a função-membro retorna - provavelmente terá que modificar todos os códigos que chamam a função-membro. Quanto menor for a interface pública, maior o encapsulamento e, portanto, maior a flexibilidade.

É claro que vale a pena minimizar a interface pública, mas freqüentemente o que não é tão claro é que você também deseja minimizar a interface protegida. A idéia básica é que, do ponto de vista de uma subclasse, as interfaces protegidas de todas as suas superclasses são efetivamente públicas. Qualquer função-membro na interface protegida pode ser chamada por uma subclasse. Portanto, você deseja minimizar a interface protegida de uma classe pelas mesmas razões que deseja minimizar a interface pública.

7.1.4.1    Defina Primeiro a Interface Pública

Os desenvolvedores mais experientes definem a interface pública de uma classe antes de começar a codificá-la. 

• Primeiro, se você não souber quais serviços ou comportamentos uma classe irá desempenhar, ainda há algum trabalho de design a ser feito.
• Segundo, isso permite fazer stub da classe rapidamente para que outros desenvolvedores que dependam dela possam pelo menos trabalhar com o stub até que a classe "real" seja desenvolvida. 
  
• Terceiro, essa abordagem fornece uma estrutura inicial em torno da qual a classe será construída.

7.2    Padrões para Interfaces

Os padrões importantes para interfaces têm como base:

• Convenções de nomenclatura
• Convenções de documentação

7.2.1    Nomeando Interfaces

A convenção Java é nomear interfaces utilizando composição de letras maiúsculas e minúsculas, com a primeira letra de cada palavra em maiúsculas. A convenção Java preferida para o nome de uma interface é utilizar um adjetivo descritivo, tais como Runnable ou Cloneable, embora substantivos descritos, tais como Singleton ou DataInput, também sejam comuns [GOS96].

7.2.1.1    Alternativa

Com algumas exceções discutidas a seguir, você deve sempre utilizar descritores completos em inglês ao nomear coisas. Além disso, você deve utilizar letras minúsculas em geral, mas utilize maiúsculas para a primeira letra dos nomes das classes e interfaces, bem como a primeira letra de qualquer palavra não-inicial.

Conceitos Gerais:

• Utilize descritores completos em inglês.
• Utilize a terminologia aplicável ao domínio.
• Utilize nomes compostos por letras maiúsculas e minúsculas para torná-los legíveis.
• Utilize formas curtas com moderação, mas se o fizer, utilize-as com inteligência.
• Evite nomes longos (menos de 15 caracteres é uma boa idéia).
• Evite nomes semelhantes ou que sejam diferentes apenas em maiúsculas e minúsculas.
• Evite sublinhados.

Item	Convenção de Nomenclatura	Exemplo
Argumentos/ parâmetros	Utilize uma descrição completa em inglês do valor/objeto que está sendo transmitido, possivelmente prefixando o nome com "a" ou "an". O fato importante é escolher uma abordagem e continuar com ela.	customer, account, - ou - aCustomer, anAccount
Campos/ campos/ propriedades	Utilize uma descrição completa em inglês do campo, com a primeira letra em minúsculas e a primeira letra de qualquer palavra não-inicial em maiúsculas.	firstName, lastName, warpSpeed
Funções-membro getter booleanas	Todos os getters booleanos devem ter como prefixo a palavra "is". Se você seguir o padrão de nomenclatura para campos booleanos descrito acima, simplesmente dê a ele o nome do campo.	isPersistent(), isString(), isCharacter()
Classes	Utilize uma descrição completa em inglês, com as primeiras letras de todas as palavras em maiúsculas.	Customer, SavingsAccount
Arquivos de unidade de compilação	Utilize o nome da classe ou interface ou, se houver mais de uma classe no arquivo, a classe primária, finalizada com ".java" para indicar que ele é um arquivo de código fonte.	Customer.java, SavingsAccount.java, Singleton.java
Componentes/ widgets	Utilize uma descrição completa em inglês que descreva para que o componente é utilizado, com o tipo do componente concatenado no final.	okButton, customerList, fileMenu
Construtores	Utilize o nome da classe.	Customer(), SavingsAccount()
Destrutores	Java não tem destrutores, mas em vez disso chamará a função-membro finalize() antes que um objeto tenha o lixo coletado.	finalize()
Exceções	Geralmente é aceito utilizar a letra "e" para representar exceções.	e
Campos estáticos finais (constantes)	Utilize todas as letras maiúsculas com as palavras separadas por sublinhados. Uma melhor abordagem é utilizar funções-membro getter estáticas finais porque elas aumentam em muito a flexibilidade .	MIN_BALANCE, DEFAULT_DATE
Funções-membro getter	Prefixe o nome do campo que está sendo acessado com "get".	getFirstName(), getLastName(), getWarpSpeeed()
Interfaces	Utilize uma descrição completa em inglês que descreva o conceito encapsulado pela interface, com as primeiras letras de todas as palavras em maiúsculas. É comum sufixar o nome com "able", "ible" ou "er", mas isso não é requerido.	Runnable, Contactable, Prompter, Singleton
Variáveis locais	Utilize descrições completas em inglês com a primeira letra em minúsculas, mas não oculte campos/campos existentes. Por exemplo, se tiver um campo denominado "firstName", não tenha uma variável local denominada "firstName".	grandTotal, customer, newAccount
Contadores de loop	É geralmente aceito utilizar as letras i, j ou k ou o nome counter.	i, j, k, counter
Pacotes	Utilize descrições completas em inglês, utilizando composição de letras maiúsculas e minúsculas com a primeira letra de cada palavra em maiúsculas, e todo o restante em minúsculas. Para pacotes globais, reverta o nome do domínio da Internet e concatene o nome do pacote a isso.	java.awt, com.ambysoft.www. persistence.mapping
Funções-membro	Utilize uma descrição completa em inglês sobre o que a função-membro faz, iniciando com um verbo ativo sempre que possível, com a primeira letra em minúsculas.	openFile(), addAccount()
Funções-membro setter	Prefixe o nome do campo que está sendo acessado com "set".	setFirstName(), setLastName(), setWarpSpeed()

11.2    Convenções de Documentação Java

11.2.1    Tipos de Comentário Java

O gráfico a seguir descreve os três tipos de comentários Java e usos sugeridos para eles.

Tipo de Comentário	Uso	Exemplo
Documentação	Utilize comentários de documentação imediatamente antes de declarações de interfaces, classes, funções-membro e campos para documentá-los. Os comentários de documentação são processados pelo javadoc (consulte a seguir) para criar documentação externa para uma classe.	/** Customer: A customer is any person or organization that we sell services and products to. @author S.W. Ambler */
Estilo C	Utilize comentários em estilo C para documentar linhas de código que não mais são aplicáveis, mas que deseja manter para o caso dos usuários mudarem de idéia, ou porque deseja desativá-las temporariamente durante a depuração.	/* This code was commented out by B.Gustafsson, June 4 1999 because it was replaced by the preceding code. Delete it after two years if it is still not applicable. . . . (the source code ) */
Linha única	Utilize os comentários de linha única internamente nas funções-membro para documentar a lógica de negócios, seções de código e declarações de variáveis temporárias.	// Apply a 5% discount to all invoices // over $1000 as defined by the Sarek // generosity campaign started in // Feb. of 1995.

O gráfico a seguir resume o que documentar relativo a cada parte do código Java gravado.

Item	O que Documentar
Argumentos/ parâmetros	O tipo do parâmetro Para que ele deve ser utilizado Quaisquer restrições ou condições prévias Exemplos
Campos/ campos/propriedades	Sua descrição Documentar todas as invariantes aplicáveis Exemplos Problemas de simultaneidade Decisões de visibilidade
Classes	O objetivo da classe Erros conhecidos O histórico de desenvolvimento e manutenção da classe Documentar invariantes aplicáveis A estratégia de simultaneidade
Unidades de Compilação	Cada classe ou interface definida na classe, incluindo uma descrição breve O nome do arquivo e/ou as informações de identificação Informações de direitos autorais
Função-membro getter	Documentar porque a inicialização foi utilizada, se aplicável
Interfaces	O objetivo Como devem e não devem ser utilizadas
Variáveis locais	Seu uso ou objetivo
Funções-membro: Documentação	O que e porque a função-membro faz o que faz Qual função-membro deve ser transmitida como parâmetro O que uma função-membro retorna Erros conhecidos Todas as exceções emitidas por uma função-membro Decisões de visibilidade Como uma função-membro altera o objeto Inclua um histórico de todas as alterações de código Exemplos de como chamar a função-membro, se apropriado Condições prévias e posteriores aplicáveis
Funções-membro: Comentários internos	Estruturas de controle Por que, e também o que, o código faz Variáveis locais Código difícil ou complexo A ordem de processamento
Pacote	O fundamento lógico do pacote As classes no pacote

11.3    Convenções de Codificação Java (geral)

Existem muitas convenções e padrões que são críticos à capacidade de manutenção e aprimoramento do seu código Java. 99,9% do tempo é mais importante programar para pessoas, seus colegas desenvolvedores, do que programar para a máquina. Tornar seu código compreensível por outras pessoas é de máxima importância.

Destino de Convenção	Convenção
Funções-membro do Acessador	Considere a utilização de inicialização adiada para campos no banco de dados Utilize acessadores para obter e modificar todos os campos Utilize acessadores para "constantes" Para coleções, inclua funções-membro para inserir e remover itens Sempre que possível, torne os acessadores protegidos, não públicos
Campos	Os campos devem sempre ser declarados privados Não acesse diretamente os campos; em vez disso, utilize funções-membro do acessador Não utilize campos estáticos finais (constantes); em vez disso, utilize funções-membro do acessador Não oculte nomes Sempre inicialize campos estáticos
Classes	Minimize as interfaces públicas e protegidas Defina a interface pública para uma classe antes de começar a codificá-la Declare os campos e funções-membro de uma classe na seguinte ordem: construtores finalize() funções-membro públicas funções-membro protegidas funções-membro privadas campo privado
Variáveis locais	Não oculte nomes Declare uma variável local por linha de código Documente variáveis locais com um comentário seqüencial Declare variáveis locais imediatamente antes de seu uso Utilize variáveis locais apenas para uma coisa
Funções-membro	Documente seu código Utilize parágrafo em seu código Utilize espaço em branco, uma linha antes das estruturas de controle e duas antes de declarações de função-membro Uma função-membro deve ser compreensível em menos de trinta segundos Grave linhas de comando curtas e simples Restrinja a visibilidade de uma função-membro o máximo possível Especifique a ordem das operações

12    Referências

Código de Referência	Informações Relacionadas
[AMB98]	Ambler, S.W. (1998). Building Object Applications That Work: Your Step-By-Step Handbook for Developing Robust Systems with Object Technology. New York: SIGS Books/Cambridge University Press.
[COA97]	Coad, P. and Mayfield, M. (1997). Java Design: Building Better Apps & Applets. Upper Saddle River, NJ: Prentice Hall Inc.
[DES97]	DeSoto, A. (1997). Using the Beans Development Kit 1.0 February 1997: A Tutorial. Sun Microsystems.
[GOS96]	Gosling, J., Joy, B., Steele, G. (1996). The Java Language Specification. Reading, MA: Addison Wesley Longman Inc.
[GRA97]	Grand, M. (1997). Java Language Reference. Sebastopol, CA: O. Reilly & Associates, Inc.
[KAN97]	Kanerva, J. (1997). The Java FAQ. Reading, MA: Addison Wesley Longman Inc.
[KOE97]	Koenig, A. (1997). The Importance--and Hazards--of Performance Measurement. New York: SIGS Publications, Journal of Object-Oriented Programming, January, 1997, 9(8), pp. 58-60.
[LAF97]	Laffra, C. (1997). Advanced Java: Idioms, Pitfalls, Styles and Programming Tips. Upper Saddle River, NJ: Prentice Hall Inc.
[LEA97]	Lea, D. (1997). Concurrent Programming in Java: Design Principles and Patterns. Reading, MA: Addison Wesley Longman Inc.
[MCO93]	McConnell, S. (1993). Code Complete: A Practical Handbook of Software Construction. Redmond, WA: Microsoft Press.
[MEY88]	Meyer, B. (1988). Object-Oriented Software Construction. Upper Saddle River, NJ: Prentice Hall Inc.
[NAG95]	Nagler, J. (1995). Coding Style and Good Computing Practices. http://wizard.ucr.edu/~nagler/coding_style.html
[SUN96]	Sun Microsystems (1996). javadoc - The Java API Documentation Generator. Sun Microsystems.
[SUN97]	Sun Microsystems (1997). 100% Pure Java Cookbook for Java Developers: Rules and Hints for Maximizing the Portability of Java Programs. Sun Microsystems.
[VIS96]	Vision 2000 CCS Package and Application Team (1996). Coding Standards for C, C++, and Java. http://v2ma09.gsfc.nasa.gov/coding_standards.html

13    Glossário

100% puro: Efetivamente um "selo de aprovação" da Sun que diz que um applet, aplicativo ou pacote Java será executado em QUALQUER plataforma que suporte a Java VM.

Acessador: Uma função-membro que modifica ou retorna o valor de um campo. Também conhecido como um modificador de acesso. Consulte Getter e Setter.

Padrão de análise: Um padrão de modelagem que descreve uma solução para um problema de domínio ou negócio.

Antipadrão: Uma abordagem para resolver um problema comum, que com o tempo prova ser incorreto ou altamente ineficaz.

Argumento: Consulte parâmetro.

BDK: Beans Development Kit

Bloco: Uma coleção de zero ou mais instruções contidas entre parênteses.

Parênteses: Os caracteres { e }, conhecidos respectivamente como parêntese de abertura e parêntese de fechamento, são utilizados para definir o início e o fim de um bloco.

Classe: Uma definição, ou gabarito, a partir do qual os objetos são instanciados.

Teste de classe: O ato de assegurar que uma classe e suas instâncias (objetos) são executados conforme definido.

CMVC: Configuration Management and Version Control

Unidade de compilação: Um arquivo de código fonte, seja físico no disco ou "virtual" armazenado em um banco de dados, no qual classes e interfaces são declaradas.

Componente: Um widget de interface, tal como uma lista, botão ou janela.

Getter de constante: Uma função-membro getter que retorna o valor de uma "constante", que pode, por sua vez, estar em código permanente ou ser calculada se necessário.

Construtor: Uma função-membro que executa quaisquer inicializações necessárias quando um objeto é criado.

Contenção: Um objeto contém outros objetos com os quais ele colabora para desempenhar seus comportamentos. Isso pode ser realizado com a utilização de classes internas (JDK 1.1+) ou a agregação de instâncias de outras classes dentro de um objeto (JDK 1.0+).

CPU: Unidade de Processamento Central

Comentários em estilo C: Um formato de comentário Java, /* e */, adotado a partir da linguagem C/C++, que pode ser utilizado para criar comentários de várias linhas. Normalmente utilizados para "documentar" linhas de código desnecessárias ou não desejadas durante o teste.

Padrão de design: Um padrão de modelagem que descreve uma solução para um problema de design.

Destrutor: Uma função-membro de classe C++ utilizada para remover um objeto da memória quando ele não mais for necessário. Como o Java gerencia sua própria memória, esse tipo de função-membro não é necessário. O Java suporta, entretanto, uma função-membro semelhante em conceito, denominada finalize().

Comentários de documentação: Um formato de comentário Java, /** e */, que pode ser processado pelo javadoc para fornecer documentação externa para um arquivo de classe. A documentação principal para interfaces, classes, funções-membro e campos deve ser escrita com comentários de documentação.

Campo: Uma variável, do tipo de dados literal ou outro objeto, que descreve uma classe ou uma instância de uma classe. Os campos de instância descrevem objetos (instâncias) e os campos estáticos descrevem classes. Os campos também são referidos como campos, variáveis de campo e propriedades.

finalize(): Uma função-membro chamada automaticamente durante a coleta de lixo, antes que um objeto seja removido da memória. O objetivo dessa função-membro é fazer qualquer limpeza necessária, tal como fechar arquivos abertos.

Coleta de lixo: O gerenciamento automático de memória, em que os objetos que não mais são referidos são removidos automaticamente da memória.

Getter: Um tipo de função-membro do acessador que retorna o valor de um campo. Um getter pode ser utilizado para responder o valor de uma constante, o que normalmente é preferível a implementar a constante como um campo estático, pois isso é uma abordagem mais flexível.

HTML: Linguagem de marcação de hipertexto, um formato padrão de mercado para criar páginas da Web.

Recuo: Consulte utilização de parágrafo.

Comentários seqüenciais: A utilização de um comentário de linha para documentar uma linha de código fonte, em que o comentário segue imediatamente o código, na mesma linha que este. Os comentários de linha única normalmente são utilizados para isso, embora os comentários em estilo C também possam ser empregados.

Interface: A definição de uma assinatura comum, incluindo funções-membro e campos, que uma classe que implementa uma interface deve suportar. As interfaces promovem o polimorfismo por composição.

E/S: Entrada/Saída

Invariante: Um conjunto de asserções sobre uma instância ou classe que devem ser verdadeiras em todos os momentos "estáveis", tais como os períodos antes e depois da chamada de uma função-membro no objeto ou classe.

Java: Uma linguagem de desenvolvimento padrão de mercado orientada a objetos que é bastante adequada para o desenvolvimento de aplicativos para a Internet e aplicativos que devem operar em uma variedade de plataformas de computação.

javadoc: Um utilitário incluído no JDK que processa um arquivo de código fonte Java e produz um documento externo, em formato HTML, descrevendo o conteúdo do arquivo de código fonte com base nos comentários de documentação no arquivo de código.

JDK: Java Development Kit

Inicialização adiada: Uma técnica na qual um campo é inicializado em sua função-membro getter correspondente na primeira vez em que for necessário. A inicialização adiada é utilizada quando um campo não é normalmente necessário e requer uma grande quantidade de memória para armazenamento ou precisa ser lido a partir de um armazenamento permanente.

Variável local: Uma variável definida no escopo de um bloco, normalmente uma função-membro. O escopo de uma variável local é o bloco no qual ela está definida.

Função-membro: Um trecho de código executável associado a uma classe ou a instâncias de uma classe. Pense na função-membro como o equivalente orientado a objetos de uma função.

Assinatura da função-membro: Consulte assinatura.

Teste de método: O ato de assegurar que uma função-membro é executada conforme definido.

Ocultação de nome: A prática de utilizar o mesmo nome, ou pelo menos um semelhante, para um campo, variável ou argumento que o de um com escopo superior. O abuso mais comum da ocultação de nome é nomear uma variável local da mesma forma que um campo da instância. A ocultação de nome deve ser evitada pois torna o código mais difícil de entender e propenso a erros.

Sobrecarregar: Uma função-membro é dita sobrecarregada quando está definida mais de uma vez na mesma classe (ou em uma subclasse); a única diferença é a assinatura de cada definição.

Substituir: Uma função-membro é dita substituída quando é redefinida em uma subclasse e tem a mesma assinatura que a definição original.

Pacote: Uma coleção de classes relacionadas.

Utilização de parágrafo: Uma técnica onde você recua o código dentro do escopo de um bloco de código por uma unidade, normalmente uma tabulação horizontal, de forma a distingui-lo do código fora do bloco de código. A utilização de parágrafo ajuda a aumentar a legibilidade do código.

Parâmetro: Um argumento transmitido para uma função-membro, um parâmetro pode ser um tipo definido, como string ou int, ou um objeto.

Condição posterior: Uma propriedade ou asserção que será verdadeira depois que a execução de uma função-membro for concluída.

Condição prévia: Uma restrição sob a qual uma função-membro funcionará corretamente.

Propriedade: Consulte campo.

Setter: Uma função-membro do acessador que define o valor de um campo.

Assinatura: A combinação do tipo de parâmetros, se houver, e sua ordem que deve ser transmitida para uma função-membro. Também é chamada de assinatura da função-membro.

Comentários de linha única: Um formato de comentário Java, // , adotado a partir da linguagem C/C++ que é normalmente utilizado para a documentação interna de função-membro da lógica de negócios.

Tags: Uma convenção para marcar seções especificadas dos comentários de documentação que serão processadas pelo javadoc para produzir comentários com aparência profissional. Exemplos de tags incluem @see e @author.

Ferramentas de teste: Uma coleção de funções-membro para testar seu código.

UML: Idioma unificado de modelagem, que é uma notação de modelagem padrão de mercado.

Visibilidade: Uma técnica utilizada para indicar o nível de encapsulamento de uma classe, função-membro ou campo. As palavras-chave - public, protected e private - podem ser utilizada para definir a visibilidade.

Espaço em branco: Linhas em branco, espaços e tabulações incluídas no código para aumentar sua legibilidade.

Widget: Consulte componente.