Item 74 - Documente todas as exceções lançadas por cada método

Importância:

• A documentação das exceções lançadas é essencial para o uso correto de métodos.
• Sem a documentação adequada, outros programadores podem ter dificuldade em utilizar suas classes ou interfaces.

Regras para documentação:

• 1. Use a tag @throws no Javadoc:
• Documente todas as exceções verificadas e não verificadas.

/**
 * Calcula a raiz quadrada de um número.
 *
 * @param value o número cuja raiz quadrada será calculada
 * @return a raiz quadrada do número
 * @throws IllegalArgumentException se o número for negativo
 */
public double calculateSquareRoot(double value) {
    if (value < 0) {
        throw new IllegalArgumentException("O número não pode ser negativo.");
    }
    return Math.sqrt(value);
}

Declare exceções verificadas individualmente:

• Inclua-as na cláusula throws e documente as condições em que são lançadas.
• Não use superclasses genéricas como Exception ou Throwable.

/**
 * Lê dados de um arquivo.
 *
 * @param file o arquivo a ser lido
 * @return os dados lidos
 * @throws IOException se ocorrer um erro de I/O
 */
public String readFile(File file) throws IOException {
    // Implementação...
}

Documente exceções não verificadas:

• Mesmo que a linguagem não exija, descreva as exceções não verificadas para ajudar os programadores a evitarem erros.

/**
 * Divide dois números.
 *
 * @param numerator o numerador
 * @param denominator o denominador
 * @return o resultado da divisão
 * ArithmeticException se o denominador for zero
 */
public int divide(int numerator, int denominator) {
    if (denominator == 0) {
        throw new ArithmeticException("Divisão por zero não é permitida.");
    }
    return numerator / denominator;
}

Documentação em nível de classe:

• Para exceções comuns, como NullPointerException, documente no nível da classe quando aplicável a vários métodos.

/**
 * Esta classe realiza operações matemáticas.
 * 
 * <p>Todos os métodos desta classe lançam uma {@code NullPointerException} se
 * algum parâmetro for {@code null}.</p>
 */
public class MathOperations {
    // Implementação...
}

Exceções a essas regras:
Método main:

• Pode declarar throws Exception, pois é chamado pela JVM

public static void main(String[] args) throws Exception {
    // Implementação...
}

Revisões futuras:

• Exceções não verificadas adicionadas após uma revisão não violam a compatibilidade, mas devem ser documentadas se possível.

Boas práticas:
Não declare exceções não verificadas em throws:

• A ausência de throws para exceções não verificadas destaca visualmente que são não verificadas.

public void doSomething() {
    // Pode lançar uma NullPointerException, mas não a declaramos em "throws".
}

Documente exceções não verificadas como precondições:

• Descreva as condições necessárias para que o método funcione sem lançar exceções.

Evite classes genéricas em throws:

• Declarações como throws Exception ou throws Throwable escondem detalhes importantes.

Evitar:

public void doSomething() throws Exception {
    // Não recomendado
}

Resumo de implementação:
Use @throws para documentar todas as exceções:

/**
 * Processa uma lista de itens.
 *
 * @param items a lista de itens a ser processada
 * @throws NullPointerException se a lista for {@code null}
 * @throws IllegalArgumentException se a lista estiver vazia
 */
public void processItems(List<String> items) {
    if (items == null) {
        throw new NullPointerException("A lista não pode ser null.");
    }
    if (items.isEmpty()) {
        throw new IllegalArgumentException("A lista não pode estar vazia.");
    }
    // Processamento...
}

Documente no nível da classe para exceções recorrentes:

/**
 * Classe responsável por operações em arquivos.
 *
 * <p>Todos os métodos desta classe lançam uma {@code NullPointerException}
 * se um arquivo {@code null} for passado.</p>
 */
public class FileOperations {
    // Métodos...
}