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.
CODE
/**
* 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.
CODE
/**
* 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.
CODE
/**
* Divide dois números.
*
* @param numerator o numerador
* @param denominator o denominador
* @return o resultado da divisão
* @throws 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.
CODE
/**
* 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
CODE
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.
CODE
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:
CODE
public void doSomething() throws Exception {
// Não recomendado
}
Resumo de implementação:
Use @throws para documentar todas as exceções:
CODE
/**
* 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:
CODE
/**
* 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...
}
Vollständiger Original-Artikel
Den kompletten Beitrag mit allen Details direkt auf dev.to lesen.
SOCIAL SHARE CARD GENERATOR