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

12

13

14

Exemplo - Documentação da classe Conta

/**

* Classe de conta bancária simples.

*

* @author Fulano de Tal fulano@deinf.ufma.br

* @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

Exemplo

26

Codding standards

27

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

Caso particular

Quais padrões de código seriam úteis a XP ?

Os programas atuais respeitam estes padrões ?

Na prática, verificar que respeitar os padrões não é tão difícil.

64