Javafree

Deixando o seu código bem formatado com o uso das convenções da Sun e Javadoc

Publicado por equipejavafree em 20/12/2012 - 21.298 visualizações

Artigo escrito pelo usuário jmayer13

Nesse artigo serão apresentados as convenções Java adotadas pela Sun e o Javadoc ferramenta
criada pela Sun para documentação e as convenções SQL. Também será mostrado como configurar a
IDE NetBeans para gerar seus próprios modelos de de classes.


1. CONVENÇÕES DE CÓDIGO JAVA
Mas o que é essa convenção?
É um padrão para o desenvolvimento de códigos Java.

1.1. Nomes de Arquivo

1.1.1. Extensão de Arquivos
.java - Java source
.class - Java bytecode

1.1.2. Organização dos arquivos
Um arquivo consiste de seções que devem ser separadas por linhas em branco e opcionalmente de
um comentário identificando cada seção.

Evite arquivos de código com mais de 20.000 linhas pois ficam pesados.

1.1.3. Arquivos de código Java
Cada arquivo de código Java contem uma única classe publica ou interface. Quando classes privadas e
interfaces são associadas com uma classe publica, você pode colocá-los no mesmo no mesmo arquivo de
código da classe publica. A classe pública deve ser a primeira classe ou interface no arquivo.

Arquivos de código Java devem seguir a ordem:
- Comentário Inicial;
- Declaração do Package e Imports;
- Declaração de classes e interfaces;

1.1.3.1. Comentário Inicial
Todos os arquivos de código deveriam iniciar com um comentário estilo C (/*...*/) que lista o
programador(es), a data, um aviso de direitos autorais (copyright notice) e também uma breve descrição
do propósito do programa. Por Exemplo:

1.1.3.2. Declaração de Package e Imports
A primeira linha não comentada da maioria dos arquivos de códigos Java é a declaração do Package. Depois
disso, é seguido da declaração dos imports. Por exemplo:

1.1.3.3. Declaração de classes e interfaces
A tabela a seguir descreve as partes de uma declaração de uma classe ou interface, na ordem em que ela
deve aparecer.

0

1.2. Indentação
Devem ser usados quatro espaços como uma unidade de indentação. A exata constituição de uma indenização
não é especificada (Tabs ou espaços). Tabs devem ser de exatamente 8 espaços (não 4).

1.2.1. Comprimento da Linha
Evite linhas com mais de 80 caracteres, uma vez que elas não são bem manipuladas por terminais e algumas
ferramentas.

NOTA: Exemplos para uso em documentação devem ter linhas mais curtas - geralmente não mais que 70
caracteres.

1.2.2. Quebra de linhas
Quando uma expressão não couber em uma única linha, quebre-a com os seguintes princípios gerais:
- Quebre depois da virgula.
- Quebre antes do operador.
- Prefira quebra de linha no nível mais alto do que no nível mais baixo.
- Alinhe a nova linha com o mesmo nível que o inicio da expressão da linha anterior.
- Se as regras acima conduzirem a um código confuso ou a um código esmagado na margem direita, então
apenas indetente 8 espaços.

Aqui estão alguns exemplos de quebra linha:

A seguir temos dois exemplos de quebra de linha em expressões aritméticas. O primeiro é o indicado, uma
vez que a quebra ocorre fora dos parenteses da expressão, que estão no nível
superior.

A seguir temos dois exemplos de indentação de declaração de métodos. O primeiro é um caso convencional. O
segundo passaria a segunda e terceira linha para a extremidade direita se fosse usada a indentação
convencional, então em vez disso é indentado apenas 8
espaços.

Quebra de linha para declaração if geralmente devem usar a regra de 8 espaços, uma vez que a
convencional(4 espaços) torna com que o corpo difícil de ver.


1.3. Comentários
Programas Java podem conter dois tipos de comentários:
Comentários de implementação - aqueles encontrados em C, servem para comentar o código ou uma
implementação em particular.

Podem ser delimitados por

ou ainda

Comentário de documentação - usados na documentação com o Javadoc.
São definidos por

Comentários devem ser usados para dar uma visão geral do código e prover informações adicionais aquilo
que não esta prontamente disponível no próprio código. Comentários devem conter somente informações
relevantes para a leitura e compreensão do programa.

1.4. Declarações
1.4.1. Numero por linha
Uma declaração por linha é recomendada visto desde que ela incentiva a comentar. Em outras palavras,

é preferido em relação á

Em hipótese nenhuma uma variáveis e funções podem ser declaradas na mesma linha.

Não coloque tipos diferentes na mesma linha.

NOTA: Os exemplos acima usam um espaço entre o tipo e o identificador. Outra alternativa aceitável é usar
tabs.

1.4.2. Localização
Somente coloque declarações no começo de blocos. Não espere para declarar variáveis quando elas forem
usadas uma primeira vez.

1.4.3. Inicialização
Tente inicializar variáveis locais onde elas são declaradas. A única razão para não inicializar uma
variável onde está esta declarada é se o valor inicial depende de alguns cálculos que ocorrem primeiro.

1.4.4. Declaração de Classes e Interfaces
Quando escrevermos classes e interfaces Java, as seguintes regras devem ser seguidas :
- Sem espaço entre o nome do método e o parenteses que inicia a sua lista de parâmetros
- Abrir colchetes "{" aparece no final da mesma linha que o comando de declaração.
- Fecha colchetes "{" inicia em uma linha própria recuando para combinar com a abertura de colchetes, da
correspondente declaração, exceto quando a declaração é nula neste caso o "}" deve seguir imediatamente
depois do "}".

- Métodos devem ser separados por uma linha em branco.

1.5. Declarações
1.5.1. Declarações Simples
Cada linha deve conter apenas uma declaração. Exemplo:

Não use virgula para agrupar varias instruções a menos que seja por uma razão óbvia. Exemplo:

1.5.2. Declaração Complexas
Declarações compostas são declarações que contem listas de instruções entre as chaves "{ Declarações }".
Veja as seguintes seções para exemplos.
- As declarações fechadas devem ser indentadas um nível mais do que o comando composto;
- A abertura de colchetes deve estar no final da linha que se inicia a expressão composta; o fechamento
de colchetes deve começar uma linha e ser recuado para o início da expressão composta;
- Colchetes são usadas em torno todas as declarações, até mesmo em declarações individuais, quando elas
fazem parte de uma estrutura de controle, como uma instrução if-else ou for. Isto torna mais fácil
adicionar declarações sem acidentalmente gerar erros, devido à falta de colchetes.

1.5.3. Declaração return
Uma declaração return com um valor não deve usar parenteses, a menos que eles façam o valor de retorno
mais obvio de alguma forma ou é claro, o retorno seja uma expressão.

1.5.4 Declaração if, if-else, if-else-if-else
A classe de declaração if-else deve seguir a seguinte forma:

NOTA: Sempre use colchetes {} em declarações if . Evite a seguinte forma propensa a erro:

1.5.5. Declaração for
A declaração for deve seguir a seguinte forma:

1.5.6. Declaração while
Uma declaração while deve seguir a seguinte forma;

1.5.7. Declaração do-while
Uma declaração do-while

1.5.8. Declaração switch
Uma declaração switch deve seguir a seguinte forma;

Toda vez que um case passa através (não inclui a instrução break), adicione um comentário onde a
instrução break normalmente estaria.

1.5.9 Declaração try-catch
Uma declaração try-catch deve seguir a seguinte forma;


1.6. Espaços em Branco
1.6.1. Linhas em branco
Linhas em branco melhoram a legibilidade definindo seções de código que são relacionadas logicamente.

Duas linhas em branco devem sempre ser usadas nas seguintes circunstancias.
- Entre seções de arquivos de um arquivo de código
- Entre as definições de classe e interfaces

Uma linha em branco devem sempre ser usadas nas seguintes circunstancias.
- Entre métodos
- Entre as variáveis locais em um método e sua primeira declaração
- Antes de um comentário de bloco ou comentário de linha
- Entre seções lógicas dentro de um método para melhorar a legibilidade

1.6.2. Espaços em branco
Espaços em branco devem sempre ser usadas nas seguintes circunstancias.
- Uma palavra chave seguida por um parentese deve ser separada por um espaço. Exemplo:

Note que um espaço em branco não deve ser usado entre o nome do método e a abertura de parenteses. Isto
ajuda a distinguir palavras-chave de chamadas de métodos.
- Uma linha em branco deve aparecer depois da virgula em uma lista de argumentos.
- Todo o operador binário exceto "." deve ser separado de outros operadores por espaço. Espaço em branco
nunca devem separar operadores unários, como incremento (?++?) e decremento (?--?) de seus operandos.
- As expressões em uma declaração for deve ser separada por espaço em branco.
- Cats devem ser sempre seguidos por um espaço em branco.

1.7. Convenções de Nomes
Convenções de nomes tornam os programas mais compreensíveis tornando-os mais fáceis de ler. Elas também
podem fornecer informação sobre a função do identificador.

0

1.8. Práticas de Programação
1.8.1. Fornecer acesso a variáveis de instancia e de classes
Não faça qualquer instancia ou variável de classe public, sem uma boa razão.

1.8.2. Referindo-se a variáveis e métodos de classe
Evite usar um objeto para acessar uma classe (static) ou método. Use um nome de classe em vez disso. Por
exemplo:

1.8.3. Constantes
Constantes numéricas não devem ser codificadas diretamente., exceto por -1, 0 e 1, que podem aparecer em
um loop for como valor de contador.

1.8.4. Atribuições de Variáveis
Evite atribuir diversas variáveis com o mesmo valor em uma única instrução. É difícil de ler.

Não use o operador de atribuição em um lugar onde ele pode ser facilmente confundido com o operador de
igualdade.

1.8.5. Parenteses
É geralmente uma boa ideia usar livremente parenteses numa expressão envolvendo operadores mistos para
evitar problemas de precedência de operadores. Mesmo se a precedência do operador parecer clara para
você, ela não pode ser para outros.


2. JAVADOC
Puts.. para que eu vou utilizar Javadoc, não vou documentar ?
OK, mas não necessariamente precisa usar o Javadoc para documentar. O Javadoc tem um padrão de tags (que
sará apresentado a seguir) que descrevem os métodos e
as classes, esse padrão ajuda a deixar o código mais claro e "limpo".

Relembrando: Javadoc é a ferramenta utilizada para criar arquivos HTML que documentam o código Java.

2.1. Criando Documentação com Javadoc
2.1.1. Comentários de documentação
Antes que arquivos de HTML possam ser gerados com a ferramenta Javadoc, programadores devem inserir comentários especiais - chamados comentários de
documentação.
Como já foi visto, comentários de documentação são constituídos por

Uma vez que Javadoc é utilizado para criar arquivos HTML, os comentários de documentação podem ser
inseridos com tags HTML.
A seguir algumas das tags que podem ser usadas para formatar os comentarios.

0

2.1.2. Documentando o código-fonte Java
Os comentários de documentação são colocados na linha antes de uma declaração de classe, uma declaração
de interface, um construtor, um método e um campo( ou
seja, uma variável de instancia ou de referencia).

0

Um caractere # é utilizado em vez de um ponto rotulamos um método ou um campo. Isso cria um link ao nome
do campo ou do método que segue o caractere #.

Pela convenção do Javadoc, os programadores compõem o código-fonte (isto é, palavras chave ,
identificadores e expressões) com os tags de HTML e
.

A seguir um exemplo de uso das tags do Javadoc



2.2. Gerando a documentação Javadoc no NetBeans
Esta é a parte mais difícil até agora !

-Selecione o seu projeto.
-Clique com o botão direito sobre o mesmo.
-Vá até a opção Gerar Javadoc e clique nela.
Será gerada por padrão na pasta dist/Javadoc do seu projeto.

3. CONVENÇÕES SQL
Utiliza-se por convenção as palavras chaves do SQL em maiúsculas e os identificadores dos objetos em
minúsculas. Exemplo:


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

0

Aqui você tem varias opções pode criar uma classe a partir de um modelo ou pode editar um modelo padrão
ou ainda pode importar um arquivo .java (mas não
qualquer arquivo, um modelo) .

4.1. FreeMaker
A partir do NetBeans IDE 6.0, é possível usar opcionalmente a linguagem de modelo FreeMarker para definir
os modelos de arquivo. Vários dos modelos incluídos
no IDE são definidos dessa forma.
Algumas tags podem ser usadas em modelos, entre elas :

0

Para mais informações sobre FreeMaker consulte:
http://platform.netbeans.org/tutorials/60/nbm-filetemplates_pt_BR.html

4.2. Exemplos de modelos
No meu casso eu apenas alterei o modelo Classe Java e Classe Java Principal.
Eles ficaram assim:

Classe Java



Classe Principal Java



___________________________________________________________________________________________________________

REFERENCIAS

Java Code Convertions, Sun http://java.sun.com/docs/codeconv/CodeConventions.pdf

DEITEL Java: Como programar, 6 º Edição ,Apêndice H .
http://lcadfs2.lcad.icmc.usp.br/~junio/mat/Javadoc.pdf

Customize Your NetBeans Java Template to Fit Your Need , Athur Cheng
http://netbeans.org/competition/win-with-netbeans/customize-java-template.html