¿Cómo documenta las excepciones sin marcar?

Question

Joshua Bloch en su Effective Java escribe:

"utilice la etiqueta el Javadoc @throws para documentar cada una excepción no comprobada de que un método puede lanzar, pero no utilice los tiros de palabras clave para incluir sin marcar excepciones en la declaración del método . "

Bueno, eso suena razonable, pero ¿cómo saber qué excepción desaprovechada puede arrojar mi método?

Vamos a pensar en una clase siguiente:

public class FooClass { 

    private MyClass[] myClass; 

    /** 
    * Creates new FooClass 
    */ 
    public FooClass() { 
     // code omitted 
     // do something with myClass 
    } 

    /** 
    * Performs foo operation.<br /> 
    * Whatever is calculated. 
    * @param index Index of a desired element 
    * @throws HorribleException When something horrible happens during computation 
    */ 
    public void foo(int index) { 
     try { 
      myClass[index].doComputation(); 
     } catch (MyComputationException e) { 
      System.out.println("Something horrible happened during computation"); 
      throw new HorribleException(e); 
     } 
    } 
} 

Ahora, he documentado HorribleException, pero es bastante obvio, que el método foo también puede lanzar sin control java.lang.ArrayIndexOutOfBoundsException. Cuanto más complejo es el código, es más difícil pensar en todas las excepciones sin marcar que el método puede arrojar. Mi IDE no me ayuda mucho allí y tampoco ninguna herramienta. Como no conozco ninguna herramienta para esto ...

¿Cómo manejas este tipo de situación?

Answer 1

Solo documente las que está lanzando explícitamente o está pasando de otro método. El remanente se debe considerar como errores que se deben corregir mediante buenas pruebas unitarias y escritura de código sólido.

En este caso particular, me cuenta de ArrayIndexOutOfBoundsException como un error en el código y me arregle el código consecuencia de que nunca lo tira. Es decir. agregue un cheque si el índice de la matriz está dentro del rango y maneje en consecuencia arrojando una excepción -que documenta- o tomando una ruta alternativa.

Answer 2

La cita que publicaste, es algo que debes tener en cuenta si quieres ser el programador ideal. La programación no es pensar "lo que puede salir mal", sino pensar cómo hacer algo de la mejor manera y programarlo. Si se trata de un proyecto personal, solo escriba lo que hace el método.

Sin embargo, hay tres soluciones posibles:

• no documentan el método.
• Piense un minuto en lo que hace su código y descubra cuáles podrían ser las posibles excepciones no verificadas más comunes. Agréguelos al Java-doc. Y si encuentra uno nuevo, descubra cuál es el problema y agréguelo como posible excepción.
• No importa las posibles excepciones y documente solo las excepciones inserte el cuerpo del método (como: if (obj == null) { throw new NullPointerException(); }).

Answer 3

Tenemos una extensión de estilo de cheque escrita que se ejecuta en nuestro servidor de prueba. En tu muestra probaría si se documentó HorribleException.

La ArrayIndexOutOfBoundsException detectará con una revisión del código. En su código de ejemplo, nuestros objetivos requerían arrojar una InvalidArgumentException en lugar de una ArrayIndexOutOfBoundsException. La documentación del mismo será encontrada en el servidor de prueba.

La excepción ArrayIndexOutOfBoundsException puede ser una advertencia en FindBugs. Pero no estoy seguro.

Answer 4

documento Sólo lo que estás tirándote.

En este caso, me gustaría ir a un índice de comprobación de límites y lanzar mi propia excepción: throw IllegalArgumentException("Index must be smaller than " +myClass.length + ", but is: " + index) y luego documentar la IllegalArgumentException en el JavaDoc.

Answer 5

Cuanto más complejo es el código, es más difícil pensar en todas las excepciones no comprobadas que el método puede arrojar.

vez que veas un problema, veo una muy buena razón para mantener su código simple ;-)

En su exemple, sugeriría para documentar la ArrayIndexOutOfBoundsException. El hecho de que eso es algo que alguien puede tener al dar un mal parámetro para que el método y debe ser escrito en alguna parte: ". Si se da un índice de matriz no válida, obtendrá un ArrayIndexOutOfBoundsException Por ejemplo, los String#charAt() documentos de método puede lanzar una IndexOutOfBoundException si el índice no es válido

En general, no debe documentar todas las excepciones que puedan surgir. No puede predecirlas todas, y es muy probable que olvide una. obvias, el que a pesar de. Trate de enumerar la mayor cantidad posible de excepciones, pero no gastan mucho tiempo en él. Después de todo, si se olvida uno que debe ser documentada, puede mejorar su consulta posterior.