DEV Community

Java Efetivo (livro)
Java Efetivo (livro)

Posted on

Item 56: Escreva comentários de documentação para todos os elementos da API exposta

Documentação da API:

  • Toda API deve ser documentada para facilitar seu uso.
  • Tradicionalmente, a documentação era gerada manualmente, mas com o Javadoc isso se tornou automatizado.

Comentários doc:

  • Os comentários doc são especialmente formatados para serem lidos pelo Javadoc.
  • Eles devem ser usados em classes, interfaces, construtores, métodos e campos expostos da API.
  • É importante mantê-los sincronizados com o código.

Convenções:

  • As convenções de comentários doc não fazem parte da linguagem, mas todo desenvolvedor Java deve conhecê-las.
  • Tags úteis: {@code}, {@literal}, {@implSpec}, {@index}.

Documentação de métodos:

  • Deve descrever o contrato entre o método e o cliente.
  • Deve listar:
  • Precondições (usualmente descritas com @throws para exceções).
  • Pós-condições (o que será verdade após a execução bem-sucedida).
  • Efeitos colaterais (mudanças não óbvias no estado do sistema).
  • Utilizar @param para cada parâmetro, @return para o retorno e @throws para exceções.

Escrita de comentários:

  • O texto após @param ou @return deve ser uma frase nominal.
  • O texto após @throws deve começar com "se" e descrever a condição que gera a exceção.
  • Convencionado que as frases não têm ponto final.

Elementos HTML:

  • Tags como

    e podem ser usadas dentro dos comentários doc.

  • A tag {@code} é usada para formatar código, e {@literal} para incluir caracteres especiais como < e >.

Herança de documentação:

  • Comentários podem ser herdados com {@inheritDoc}, reduzindo a duplicação de documentação.

Documentação adicional:
Em casos complexos, recomenda-se documentos externos complementares.

Exemplo de código com Javadoc:

/**
 * Representa uma conta bancária com operações de saque e depósito.
 * <p>
 * Essa classe é thread-safe e serializável.
 * 
 * @implSpec A implementação utiliza uma trava interna para garantir a consistência do saldo.
 */
public class ContaBancaria {

    private double saldo;

    /**
     * Deposita um valor na conta.
     *
     * @param valor o valor a ser depositado, deve ser positivo
     * @throws IllegalArgumentException se o valor for negativo
     */
    public synchronized void depositar(double valor) {
        if (valor <= 0) {
            throw new IllegalArgumentException("O valor deve ser positivo.");
        }
        saldo += valor;
    }

    /**
     * Retira um valor da conta.
     *
     * @param valor o valor a ser retirado, deve ser positivo e menor que o saldo atual
     * @throws IllegalArgumentException se o valor for negativo ou maior que o saldo
     */
    public synchronized void sacar(double valor) {
        if (valor <= 0 || valor > saldo) {
            throw new IllegalArgumentException("Valor inválido.");
        }
        saldo -= valor;
    }

    /**
     * Retorna o saldo atual da conta.
     *
     * @return o saldo atual
     */
    public synchronized double getSaldo() {
        return saldo;
    }
}

Enter fullscreen mode Exit fullscreen mode

Esse exemplo demonstra o uso correto de comentários doc para uma classe ContaBancaria, incluindo tags como @param, @return, @throws e @implSpec

Top comments (0)