documentação usando o javadoc - deinf/ufma - departamento de...
TRANSCRIPT
Documentação – Usando o Javadoc
Programação Orientada a Objetos Java
Prof. Geraldo Braz Junior
Notas de aula: João Carlos Pinheiro e Alfredo Goldman
Comentários Existem três tipos de comentários possíveis:
1. Proveniente da linguagem C padrão que é útil
para comentários de grandes blocos de código e
cuja sintaxe começa com /* e continuando até o
próximo */
2. Proveniente do C++, útil para comentários curtos
em meio ao corpo código, cuja sintaxe começa
com // estendendo-se até o fim da linha
3. Comentários especiais de documentação, úteis na
geração da documentação automática. Sua
sintaxe inicia-se com /** continuando até o
próximo */
2
Documentação
O Java possui uma ferramenta para gerar documentação
apartir dos comentários inseridos no código fonte. O
javadoc
Criado pela SUN para documentar a API do código Java
Extrai os comentários especiais de documentação embutidos
no código, gerando um arquivo no formato HTML
Processa apenas comentários de documentação para
membros de classe declarados como public ou protected
Comentários em membros do tipo private serão ignorados,
se não forem explicitados no comando javadoc (lembre das
regras de encapsulamento)
3
Links para pacotes são exibidos neste frama A página web selecionada é
exibida neste frame
Links para classes e interfaces são exibidas neste frame4
Documentação ...
Há duas maneiras de se trabalhar com o javadoc:
1. Embutindo-se código HTML
2. Usando tags de documentação
Embutindo HTML
O javadoc permite o uso de comandos HTML diretamente
nos comentários de documentação
É permitido o uso de qualquer comando de formatação,
tal como <TT> e <b>, mas não se pode fazer uso de
comandos estruturais, tais como <H2> e <hr>; pois o
javadoc já insere seus próprios comandos estruturais
5
Embutindo HTML
Exemplo:/**
É possível <b> até </b> gerar uma lista
<ol><li> item um
<li> item dois
<li> item três
</ol>
*/
6
Usando tags de documentação do javadoc
Tags são comandos que permitem formatação adicional da documentação e são sempre iniciados por @
Existem 8 tags permitidas em Java
@see
@author
@version
@param
@return
@exception
@deprecated
@since7
Tags de documentação
Há 3 tipos distintos de documentação: o de Classes, o
de Atributos e o de Métodos
Alguns tags são exclusivos para cada um deles
Apenas os tags @see e @deprecated são utilizados para
qualquer dos três tipos
@see - referencia outras classes, variáveis ou métodos,
incluindo-as (via hiperlinks) na lista “See Also”
@deprecated - aviso desaconselhando o uso de
determinadas classes, métodos ou variáveis, que por
exemplo podem cair em desuso em novas versões
8
Tags de documentação ...
@since - permite indicar quando um novo
recurso foi adicionado numa classe
Tags exclusivas de Classes e interfaces.
@version - permite a inclusão de quaisquer
informações significativas quanto a versão
das classes
@author - permite a inclusão de informações
sobre o autor, ou autores, tais como nome,
email, telefone e etc.9
Tags de documentação ... Documentando Variáveis
Esse tipo de documentação não possui tags reservados, podendo fazer uso apenas dos tags @see e @deprecated, além do HTML embutido
Documentando Métodos
Esse tipo de documentação permite o uso de tagsreservados para parâmetros, valores de retorno e exceções
Tags exclusivas de métodos
@param
@return
@exception
10
Tags de documentação ... @param - permite a descrição dos parâmetros de um
método
sintaxe: @param nomeDoParametro Descrição
@return - permite a descrição do significado do valor
retornado
sintaxe: @return descrição
@exception - permite a descrição e identificação da
exceção (ou exceções) quando da chamada do método.
sintaxe: @exception nomeCompletoDaClasse descrição
11
Exemplo - Documentação da classe Conta
/**
* Classe de conta bancária simples.
*
* @author Fulano de Tal [email protected]
* @version 1.0
* <br>
* Copyright (C) 1999 Universidade Federal do
Maranhão.
*/
15
// Atributos
public class Conta {
// atributos
private String nome;
private String cpf;
private String número;
private double saldo;
16
// Construtor
/**
* Cria uma conta a partir de um nome e cpf de pessoa física, e um número de conta.
* @param nome O nome do titular da conta.
* @param cpf O CPF do titular da conta.
* @param número O número da conta.
*/
public Conta (String nome, String cpf, String número) {
this.nome = nome;
this.cpf = cpf;
this.número = número;
saldo = 0.0;
}17
Métodos accessor (accessor methods)
/**
* Recupera o número da conta.
* @return O número da conta.
*/
public int getNumero() {
return numero;
}
18
Métodos “accessor” .../**
* Recupera o nome do titular da conta.
* @return O nome do titular da conta.
*/
public String getNome() {
return nome;
}
19
Métodos “accessor” ...
/**
* Recupera o CPF do titular da conta.
* @return O CPF do titular da conta.
*/
public String getCPF() {
return cpf;
}
/**
* Recupera o saldo da conta.
* @return O saldo da conta.
*/
public double getSaldo() {
return saldo;
}20
Métodos de “comportamento”/**
* Efetua um depósito numa conta.
* @param valor O valor a depositar.
*/
public void depositar(double valor) {
// credita a conta
saldo += valor;
}
21
Métodos de “comportamento”
/**
* Efetua um saque na conta.
* @param valor O valor a sacar.
* @return O sucesso ou não da operação.
*/
public boolean sacar(double valor) {
// debita a conta
if(saldo - valor >= 0) {
saldo -= valor;
return true;
} else {
return false;
}
}22
O método toString/**
* Transforma os dados da conta em um String.
* @return A string com os dados da conta.
*/
public String toString( ) {
return "numero " + número
+ ", nome " + nome
+ ", saldo " + saldo;
}
23
Gerando a documentação
O comando javadoc tem a seguinte sintaxe:
javadoc [opções] nomedopacote ou
javadoc [opções] nomesdaclasses
24
Principais opções -classpath - conjunto de diretórios separados por vírgula
ou dois pontos (unix) onde estão as classes já
compiladas
-d – diretório onde o HTML vai ser gerado
-author - gerar informação da tag @author (default não
gera)
-noindex - suprime a geração do índice geral
-notree - suprime a geração da hierarquia de classes
-private, protected, package - documenta membros com
visibilidade até a indicada
-use - cria páginas documentando o uso de packages
windowtitle - texto para a barra de título do browser
header, footer, bottom - texto HTML em todas as páginas25
Motivação
Quem escreveu não deve ser o único a poder ler o código
Ainda mais em um sistema OO
Regras simples (muito simples) ajudam
Algumas são bem óbvias...
Criar um padrão (consensual)
Em parte independente da linguagem
28
Mais razões
80% do tempo de desenvolvimento é para manutenção;
Quase nenhum software é mantido apenas pelo primeiro desenvolvedor;
Convenções de código melhoram a legibilidade do código;
Se o código fonte é fornecido com o sistema, ele deve estar bem apresentado.
29
Porém....
Para que codding standards funcionem todos os desenvolvedores devem estar de acordo com a convenção, TODOS.
30
Resumo (baseado no padrão da sun)
Nome dos arquivos;
Estrutura dos arquivos;
Indentação;
Comentários;
Declarações;
Comandos;
Espaços em branco;
Convenção para nomes;
Práticas (simples e saudáveis) de programação.
31
Nome dos Arquivos Mesmo que a linguagem não exija, use
sufixos claros
ex. .java, .c, .cpp, .txt
Use makefiles com nomes padrão:
ex: xpmakefile
Sempre tenha no diretório um README
este arquivo deve conter um resumo do conteúdo do diretório
32
Estrutura dos Arquivos Arquivos contém seções que devem ser
separadas por linhas em branco e por comentários antes de cada seção;
Deve se evitar arquivos com mais de 2000 linhas.
33
Classes/Interfaces
Começam com um comentário do tipo /**...*/
O comando class, ou interface
Comentários sobre a implementação /*...*/
Variáveis estáticas (em ordem de acesso)
Variáveis da classe (public, protected,
friendly,private)
Construtores
Métodos (agrupados por funcionalidade e não por
escopo)
34
Indentação (é bem importante)
Use apenas espaços (tabs = 4 espaços)
Evite linhas com mais de 80 caracteres
Regras para quebra de linha:
quebra após vírgula;
quebra antes de operador;
quebra no maior nível possível;
alinhar a quebra com o começo da expressão do mesmo nível;
Se ficar feio, indentar com 8 espaços.
35
Exemplos
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = someMethod1(longExpression1,someMethod2(longExpression2,
longExpression3));
longName1 = longName2 * (longName3 + longName4 -longName5)
+ 4 *longName6; //
melhorlongName1 = longName2 * (longName3 + longName4
-longName5) + 4 *longName6; // pior
36
Exemplos// indentação tradicional
someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) {
...
}
//Indentação com 8 espaços em certos casos
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
37
Exemplos
// indentação tradicional
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //BAD WRAPS
doSomethingAboutIt(); //difícil de achar
}
// indentação proposta
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
Em ifs use geralmente a regra de indentar com 8 espaços
38
Exemplos (cont.)//Ou esta
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
// expressões ternárias
alpha = (aLongBooleanExpression) ? beta : gamma;
//ou
alpha = (aLongBooleanExpression) ? beta
: gamma;
//ou
alpha = (aLongBooleanExpression)
? beta
: gamma;
39
Comentários linhas gerais
Dois tipos de comentários (da implementação e da documentação)
Linguagens modernas tem formas específicas
use-as !
Não adicione comentários redundantes
O excesso de comentários reflete código mal escrito
pense em rescrever o trecho...
40
Comentários
Iniciar sempre o bloco comentário com uma linha em branco:/*
* Here is a block comment.
*/
Comentários de uma única linha devem ser precedidos por uma
linha em branco:if (condicao) {
/* Comentário da condição */
...
}
41
ComentáriosComentários muito curtos podem estar na mesma linha.
Se existem vários os mesmo devem estar alinhados.if (a==2) {
return TRUE; /* um caso especial */
} else {
return isPrime(a); /* funciona para a ímpar */
}
Comentários com // também podem ser usados:if (foo>2) {
// comentário de linha
...
} else {
return false; // comentário de fim de linha
}
//if (outracond==1) {
// return true; // trecho de codigo comentado
//}42
Comentários (em java usar
javadoc)Um exemplo:/**
* Class description goes here. *
* @version 1.82 18 Mar 1999* @author Firstname Lastname*/
public class Blah extends SomeClass {
/* A class implementation comment can go here. */
/** classVar1 documentation comment */
public static int classVar1;
/**
* classVar2 documentation comment that happens to be* more than one line long*/
private static Object classVar2;
43
Comentários (em java usar javadoc)
cont./** instanceVar1 documentation comment */
public Object instanceVar1;
/** instanceVar2 documentation comment */
protected int instanceVar2;
/** instanceVar3 documentation comment */
private Object[] instanceVar3;
/**
* ...constructor Blah documentation comment...*/
public Blah() {
// ...implementation goes here... }
44
Comentários (em java usar javadoc)
cont./**
* ...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... }
}
45
Declarações
Quantas por linha?
De preferência um por linha (help comments)int level; // nivel de ruídoint size; // tamanho do buraco
é melhor que:int level, size;
Nunca deve se declarar dois tipos na mesma linhaint elemento, vetor[]; // errado!
Pode-se alinhar declaraçõesint level; // indentation level
int size; // size of table
Object currentEntry; // currently selected table entry
46
Declarações Inicialização
Inicialize sempre as variáveis na hora da declaração; Exceção: variáveis que dependem de algum cálculo
47
Declarações Localização
Sempre no início de blocos; mas podem ser declaradas no início do método.
void myMethod() {int int1 = 0; // beginning of method block
if (condition) {int int2 = 0; // beginning of "if" block...
}}// o for é um caso especialfor (int i=0; i< max; i++) { ... }
Não use o mesmo nome de variável em blocos internos48
Declarações (classes e interfaces) Não dê espaço entre antes do “)”;
O “{” deve ficar no final da linha
O “}” deve estar alinhado com o comando;
Métodos devem estar separados por uma linha em branco;
Comandos vazios podem ser dados por {}.
49
Declarações (classes e interfaces)
class Sample extends Object {
int ivar1;
int ivar2;
Sample(int i, int j) {
ivar1 = i;
ivar2 = j;
}
int emptyMethod() {}
...
}
Exemplo:
50
Comandos Colocar um comando por linha;
Em um bloco indentar sempre;
Colocar { no final da linha onde começa o bloco e } alinhado com o início desta.;
Use {} mesmo quando os blocos tiverem apenas um comando.
51
Exemplos (if)
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
52
Exemplos (for)
for (initialization; condition; update) {
statements;}
for (initialization; condition; update);
// ao invés defor (init1, init2; condition; up1, up2){
statements;}
// fazerinit1;for(init2; condition; up1){
statements;up2;
}53
Exemplos (while, do while)
while (condition) {
statements;}
while (condition);
do {
statement;
} while (condition);
54
Exemplos (switch)
switch (condition) {case ABC:
statements;/* se não houver break, coloque comentário */
case DEF:statements;break;
case XYZ:statements;break;
default:statements;break; // é redundante mas pode evitar erros futuros
}
55
Espaços em Branco
Use linhas em branco para a separação lógica
duas para separar seções do mesmo arquivo;
entre definições de classes e interfaces.
uma para entre métodos;
dentro de um método entre as variáveis e o 1º comando;
antes de comentários (de bloco, ou linha);
entre as seções lógicas de um método.
56
Espaços em branco
Entre keywords e parênteses;while (true) {
... } // assim fica fácil visualizar métodos (sem espaço)
Após vírgulas em listas de argumentos;
Antes e depois de operadores binários
a += c + d;a = (a + b) / (c * d);while (d++ = s++) {
n++; // mas não para operadores unários} printSize("size is " + foo + "\n");
57
Espaços em branco
Entre os comandos de um for;for (expr1; expr2; expr3){
... }
Após operações de cast
myMethod((byte) aNum, (Object) x);myMethod((int) (cp+5), ((int) (i + 3)) + 1);
58
Nomenclatura Packages
pode-se usar domínio + subdiretórios;
Classes e Interfaces
Primeira letra de cada palavra maiúscula;
Métodos
verbos, com 1ª letra minúscula e letras de cada palavra maiúsculas;
Variáveis
1ª letra minúscula, pequenos, se temp. ok i, j, k.
Constantes
Tudo maiúsculo separado por “_”
59
Dicas de programação Evite usar um objeto para acessar algo
estático
classMethod(); //okAclass.classMethod(); //okanObject.classMethod(); //evitar
Atribuições: uma em cada linha
x = y = 0; // evitarx = 0;y = 0; // ok
d = (a = b + c) + r; //evitar
a = b + c; d = a + r; //ok
60
Dicas de programação
Use parênteses
if (a == b && c == d) //evitar
if ((a == b) && (c == d)) //ok
Use operadores ternários (em certas situações)if (cond) {
return x;}return y;
return (cond ? X : y);
Coloque o comentário XXX se há algo com problema e FIXME onde existem
bugs
61
Dicas de Programação
Se você tem métodos com mais de 80 linhas, provavelmente o código não está bem organizado;
Se seus arquivos tem mais de 500 linhas veja o item anterior;
Não use variáveis globais.
62
Padronizar o cabeçalho
/* * Nome do Arquivo: Teste.java** Descrição: Este é um arquivo que serve para testar a* classe Cliente.Java** Projeto: PDAs de venda;* Autor: Eu, tu e eles*/
63