Importância da Documentação de Código

Prévia do material em texto

Documentação de Código
Profa. Fabiana Freitas Mendes
fabianamendes@unb.br
21 de agosto de 2023
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 1 / 12
Objetivos da Aula
1 Entender sobre a importância de se comentar o código
2 Aprender como se documenta código usando o JavaDoc
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 2 / 12
Retirado do site: www. vidadeprogramador. com. br
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 3 / 12
www.vidadeprogramador.com.br
Documentação de Código
“Programe como se que o cara que vai fazer a manutenção do seu código é um
cara violento e psicopata e que sabe onde você mora!” (Martin Golding)
Os comentários servem para ajudar no entendimento do seu código e,
portanto, na manutenção dele. Escreva comentários:
No ińıcio de um método para explicar o que ele faz
Para explicar o que as variáveis mais importantes ou as estruturas de
dados criadas
Para explicar detalhes e/ou caracteŕısticas importantes do seu código
Não se esqueça de mudar o comentário quando o código mudar!
Comentário errado é pior que código sem comentário!
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 4 / 12
Você quer um exemplo de uma boa documentação
de código? Consulte a API Java!
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 5 / 12
Como fazer documentação de código em Java?
JavaDoc! Toda documentação da API Java foi criada usando
JavaDoc!
Permite escrever comentários no código que serão utilizados para
gerar uma documentação textual
Gera páginas html automaticamente a partir dos comentários
deixados no código
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 6 / 12
Elementos do JavaDoc
Para escrever comentários utilizando-se de JavaDoc, é necessária a
utilização de algumas tags. Essas tags são sempre precedidas do @
Tag Significado
@author Especifica o autor da classe ou método em questão
@deprecated Identifica classes e métodos obsoletos, não mais utilizados
@link Define um endereço url para acesso a outro documento
@param Mostra um parâmetro que será passado a um método
@return Mostra qual o tipo de retorno de um método
@see Possibilita a definição de referência de classes ou métodos
que podem ser consultadas para melhor compreender aquilo
que se está comentando
@since Indica desde quando uma classe ou método existe em uma
aplicação
@throw Indica os tipos de exceções que podem ser lançadas por um
método
@version Indica a versão da classe
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 7 / 12
Carro.java I
1 /**
2 * Classe Carro simula o comportamento de um carro e herda da classe Veiculo.
3 * @author Fabiana Freitas Mendes
4 * @since 2022
5 * @version 1.1
6 */
7 public class Carro extends Veiculo {
8
9 private boolean status;
10
11 /**
12 * Retorna o status do carro. TRUE se ligado e FALSE se desligado.
13 * @return boolean
14 */
15 public boolean getStatus () {
16 return status;
17 }
18
19 /**
20 * Altera o status do carro para TRUE (ligado ).
21 */
22 public void ligar() {
23 status = true;
24 }
25 /**
26 * Altera o status do carro para FALSE (desligado ).
27 */
28 public void desligar () {
29 status = false;
30 }
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 8 / 12
Carro.java II
31 /**
32 * Sobrescreve metodo acelerar da classe pai Veiculo.
33 * A velocidade e incrementada em 2 em relacao a velocidade atual do carro.
34 */
35 public void acelerar () {
36 final int turbo = 2;
37 float novaVelocidade = getVelocidade ();
38 if (getVelocidade () <= 10) {
39 novaVelocidade += turbo;
40 setVelocidade(novaVelocidade );
41 }
42 }
43
44 /**
45 * Sobrescreve metodo toString () das classes Object e Veiculo. Constroi
46 * uma String contendo o valor de todas as variaveis da classe Carro.
47 * @return String
48 */
49 public String toString () {
50 String status = getStatus () ? "ligado" : "desligado";
51 return "Esse␣veiculo␣e␣um␣carro.␣Marca␣=␣" +
52 this.getMarca () + ".␣Velocidade␣=␣" +
53 this.getVelocidade () + ".␣Status␣=␣" +
54 status;
55 }
56 }
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 9 / 12
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 10 / 12
Exerćıcio
Documente as classes do projeto Curso de Aperfeicoamento dispońıvel
no repositório da disciplina: www.github.com/profaFabianaMendes.
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 11 / 12
www.github.com/profaFabianaMendes
Obrigada =)
fabianamendes@unb.br
Profa. Fabiana Mendes (UnB/FGA) OO - Documentação de Código 21 de agosto de 2023 12 / 12