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;
    }
}

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