Documentação em

Linguagem Orientada a Objetos

Estudo de Caso: JavaDoc
Padrões de Codificação

Prof. Dirson Santos de Campos

[email protected]

01/10/2024
 MotivaçTópicos deste aula

 Padrõesão
de Codificação
 Ferramenta de Documentação: Estudo de Caso JavaDoc.
 Primeiro Exemplo de código fonte comentado no formato
JavaDoc

2
Padrões de
Codificação

3
 Motivaç
Por que Padronizar a Codificação de um
Código-fonte?
ão
 Na indústria de Software, nas Big Techs, em órgão
governamentais, softwares para o comércio e
indústria, em pesquisas acadêmicas e startups
envolvendo a produção de software não se desenvolve
ou muito raramente se desenvolve uma solução
sozinho, logo existem outras cabeças trabalhando no
mesmo software.
 Neste contexto, quem escreve o código não deve ser o
único a poder ler com facilidade o código
 Ainda mais em um sistema OO

4
 Motivaç
Por que Padronizar a Codificação de um
Código-fonte?
ão
 Regras simples (muito simples) ajudam
 Algumas são bem óbvias...
 Ajudam a criar um padrão (consensual)
 Em parte, padrões de codificações são independente da
linguagem, pois são boas práticas adotadas na
programação.
 Obviamente ferramentas que ajudam a padronizar
determinadas linguagem de programação variam
com a linguagem.

5
 Motivaç
Por que Padronizar a Codificação de um
Código-fonte?
ão
 Os padrões de Codificação podem ser adotados usando
ferramentas o que viabiliza a sua adoção, não precisa
ser feito manualmente a não ser que se tenha uma
regra específica da academia ou da indústria de
software.

6
 Motivaç
Por que Padronizar a Codificação de um
Código-fonte?
ão
 Existem de ferramentas que ajudam a padronizar a
codificação disponíveis em vários tipos de IDE, por
exemplo, usando o IDE Visual Studio Code com a
linguagem Java pode-se instalar a extensão no
Extension:marketplace Checkstyle for Java.
 Existem outras extensões no VS Code como pode ser
vista no próximo slide.

7
Motivaç
ão

8
 Motivaç
Por que Padronizar a Codificação de um
Código-fonte?
ão
 No IDE Eclipse usando a linguagem Java pode-se
instalar a extensão da versão deste IDE do Checkstyle
for Java.
• Instalar o Checkstyle
• Acesse o Eclipse Marketplace:
Vá para Help (Ajuda) > Eclipse Marketplace.
• Procurar por Checkstyle:
Digite "Checkstyle" na barra de busca e instale a extensão
Checkstyle Plug-in.
• Existem outros Plug-in no Eclipse como pode ser vista
no próximo slide.
9
Motivaç
ão

10
 Mais
Por que Padronizar a Codificação de um
razõesCódigo-fonte?
 Pesquisas em Engenharia de Software indicam que
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.

11
 Porém..
Padronização da Codificação

 Para que.. um padrão da codificação funcionem na

indústria ou na academia:
• Todos os desenvolvedores devem estar de acordo
com a convenção ou porque aumenta a
produtividade ou porque é imposto pelo staff da
companhia.
• A adoção de uma ferramenta facilita e muito a
adoção de um padrão.

12
Artefatos que pode se aplicar a Padronização da
Codificação
 Nome dos arquivos;
 Estrutura dos arquivos;
 Indentação; Resumo
 Comentários; (baseado no
 Declarações;
 Comandos;
padrão da sun)
 Espaços em branco;
 Convenção para nomes;
 Práticas (simples e saudáveis) de programação.
13
 Nome dos da Codificação
Padronização
Arquivos
 Mesmo que a linguagem de programação não exija, use
sufixos claros
 ex. .java, .c, .cpp, .txt
 Use nomes de atributos (variáveis), nome de métodos,
nome de pacotes, nome de classes que represente o mais
próximo possível do seu sentido semântico.
 No caso de usar ferramentas sempre tenha no diretório
um README, por exemplo, isto é corriqueiramente
adotado em ferramentas de armazenamento de software
como o Github.
 Este arquivo deve conter um resumo do conteúdo do
diretório 14
Exemplo de README da ferramenta
Nome dosno GitHub
UMLet
Arquivos

15
 Indentação
Padronização da(éCodificaçã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.

16
 Padronização da Codificação
Comentários linhas
Tipos de Comentários
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...

17
 Espaços emda Codificação
Padronização
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.

18
 Dicas de da Codificação
Padronização

 Se vocêProgramação
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.

19
Ferramenta de
Documentação
Estudo de Caso
Javadoc

20
 Ferramenta JavaDoc
Comentári

os para gerar documentação em HTML a partir do código-
JavaDoc é uma ferramenta de documentação que utiliza anotações
especiais (tags)
fonte Java.
 Página oficial:
https://www.oracle.com/java/technologies/javase/javadoc-tool.html

2 21
1
 Javadoc
Ferramenta JavaDoc
• Ferramenta Java
• Disponibilizada pelo JDK
• Interesse
• Gerar documentação HTML atualizada que pode ser por um navegador ou browser
através de um link.
• A partir de códigos-fonte Java
• Possuem aspecto padronizados e profissional
• Vantagem
• Manter num único arquivo
• Código Java
• Documentação
• Melhor do que arquivo em separados o código-fonte e a documentação
• Os requisitos podem mudar com o tempo e a documentação pode não estar em
conformidade com a implementação do software atual (última versão) 22
 Ferramenta JavaDoc
Documentaç
ão



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)

2 23
3
 Por que usar o JavaDoc?
Comentári
Design de classes
osda classe

• Especificação
– Oque um objeto deve/pode realizar.
– O usuário da classe deve conhecer (do contrário, a classe não é “útil”).
• Implementação da classe
– Como a especificação é realizada.
– Não é importante para o usuário da classe.
– Deve ser escondida do usuário da classe, pode conter
informação/conhecimento proprietário.

2 24
4
 Por que usar o JavaDoc?
Comentári

os linguagens, separamos o que pode ser
Compartilhando/escondendo informação
• Em algumas
compartilhado e o que deve ser escondido em arquivos
distintos:
– C/C++:
• Informação compartilhada: arquivos de interface *.h
• Infotmação escondida: arquivos de implementação *.c/ *.cpp
• Java
– Usa uma abordagem distinta
– Como a informação de “interface” está explícita na implementação,
utilizamos um programa, javadoc, que gera automaticamente a
documentação da classe.

2 25
5
 Por que usar o JavaDoc?
Comentári

os de implementação podem conter comentários
Documentação gerada em arquivos .html
• Os arquivos
javaDoc:
– Começam com /**
– Terminam com */

2 26
6
 Por que usar o JavaDoc?

Comentári
Existe algumas tags especiais do JavaDoc, algumas delas são:
os Especifica o autor da classe ou do método.
 @author:
 @version: Indica a versão da classe ou do método.
 @param: Descreve parâmetros de um método.
 @return: Descreve o valor de retorno de um método.
 @throws ou @exception: Indica que um método pode lançar uma
exceção.
 @see: Referencia outra classe, método ou documento relevante.
 @link: Cria um link interno na documentação.
 @deprecated: Indica que um método ou classe não deve mais ser
usado.
2 @since: Indica a versão em que um recurso foi adicionado. 27
7
 Por que usar o JavaDoc?
 Extrai Informação
 Dos ficheiros fonte
 Tipos de informação
 Código Java
 Comentários Javadoc
 Código Java
 Por omissão
 Classes públicas
 Métodos públicos
 Comentários JavaDoc
 /** ... */
 Escritos acima do código
 Exemplo
/**
* Fornece funções matemáticas
*/
public class Matematica { … } 28
 Comentários JavaDoc
 Cada Comentário
 Pode conter várias frases
 Tipos de frases
 1ª Frase
 Deve ser sumário do código
 Exemplo

Javadoc
 Javadoc
 Gera, automaticamente, páginas de sumário a partir destas frases
 Frases iniciadas pela marca @
 @param variável descrição // parâmetro de método/construtor
 @return descrição
 @version texto
29
 @author nome
 Comentários JavaDoc
Comentári
 Existem três tipos de comentários possíveis:
osProveniente da linguagem C padrão que é útil
1.
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 */

3 30
0
 Trabalhando com JavaDoc
Documentação


1.
...
Há duas maneiras de se trabalhar com o javadoc:
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

3 31
1
 Trabalhando com JavaDoc
Embutindo
Exemplo em HTML
HTML
/**
É possível <b> até </b> gerar uma lista
<ol>
<li> item um
<li> item dois
<li> item três
</ol>
*/

3 32
2
 Tipos de documentação no JavaDoc
 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

33
 Usando tags
Tags no de
JavaDoc
 documentação do
Tags são comandos que permitem
javadoc
formatação adicional da documentação e são
sempre iniciados por @
 Existem várias tags permitidas em Java, por
exemplo:
 @see
 @author
 @version
 @param
 @return
 @exception
 @deprecated
 @since 34
 Tags no JavaDoc

 @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. 35
 Tipos de documentação no JavaDoc
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 tags reservados
para parâmetros, valores de retorno e exceções.

36
 Tags exclusivas para métodos no
JavaDoc
 @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

37
Primeiro Exemplo

38
 Primeiro Exemplo
/**
* Classe de conta bancária simples.
*
* @author Fulano de Tal [email protected]
* @version 1.0
* <br>
* Copyright (C) 2024 Universidade Federal de Goiás
*/

39
 Primeiro Exemplo
public class Conta {
// atributos
private String nome; // Nome do titular da conta
private String cpf; //CPF do titular da conta
private String numero; //número da conta.
private double saldo; //Saldo da conta.

40
 Primeiro Exemplo
//
/**
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;
}
41
 Métodos
Primeiro accessor
Exemplo
(accessor
/**
methods)
* Recupera o número da conta.
* @return O número da conta.
*/
public int getNumero() {
return numero;
}

42
Primeiro Exemplo
Métodos
“accessor”
/**
...
* Recupera o nome do titular da conta.
* @return O nome do titular da conta.
*/
public String getNome() {
return nome;
}

43
 Primeiro Exemplo
/**
* 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;
}
44
 Métodos de
Primeiro Exemplo
“comportamen
/**
to”
* Efetua um depósito numa conta.
* @param valor o valor a depositar.
*/
public void depositar(double valor) {
// credita a conta
saldo += valor;
}

21 45