Comment documentez-vous les exceptions non cochées? [fermé]
Joshua Bloch dans son Java efficace écrit:
"Utilisez la balise Javadoc @throws pour documenter chaque exception décochée qui une méthode peut lancer, mais n'utilisez pas le mot-clé throws pour inclure non cochée exceptions dans la déclaration de méthode. "
Eh bien, cela semble raisonnable en effet, mais comment savoir, quelle exception non cochée ma méthode peut-elle lancer?
Pensons à une classe suivante :
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);
}
}
}
Maintenant, J'ai documenté HorribleException, mais c'est tout à fait évidemment, cette méthode foo peut également lancer non cochée java.lang.ArrayIndexOutOfBoundsException . Plus le code est complexe, il est plus difficile de penser à toutes les exceptions non cochées que la méthode peut lancer. Mon IDE ne m'aide pas beaucoup là-bas et ne fait aucun outil. Puisque je ne connais aucun outil pour cela ...
Comment gérez-vous ce genre de situation?
5 réponses
Documentez uniquement ceux que vous vous lancez explicitement ou que vous passez d'une autre méthode. Le reste doit être comptabilisé comme des bugs qui doivent être corrigés par de bons tests unitaires et l'écriture de code solide.
Dans ce cas particulier, je compterais ArrayIndexOutOfBoundsException comme un bug dans votre code et je corrigerais le code en conséquence qu'il ne le lance jamais. C'est-à-dire ajouter une vérification si l'index du tableau est dans la plage et gérer en conséquence en lançant une exception-que vous documentez - ou en prenant un chemin alternatif.
Plus le code est complexe, il est plus difficile de penser à toutes les exceptions non cochées que la méthode peut lancer.
Lorsque vous voyez un problème, je vois une très bonne raison de garder votre code simple ; -)
Dans votre exemple, je suggère de documenter le ArrayIndexOutOfBoundsException. Juste parce que c'est quelque chose que quelqu'un peut avoir en donnant un mauvais paramètre à votre méthode, et il devrait être écrit quelque part : "si vous avez donné un index de tableau invalide, vous obtiendrez un ArrayIndexOutOfBoundsException. Par exemple, la méthode String#charAt() documents il peut lancer un IndexOutOfBoundException si l'index n'est pas valide.
En général, vous ne devriez pas documenter toutes les exceptions qui peuvent survenir. Vous ne pouvez pas les prédire tous, et vous êtes très susceptible d'en oublier un. Alors, documentez les plus évidents, celui que vous avez choisi. Essayez d'énumérer le plus d'exceptions possible, mais ne passez pas beaucoup de temps dessus. Après tout, si vous oubliez celui qui devrait être documenté, vous pouvez améliorer votre documentation plus tard.
Documentez seulement ce que vous vous lancez.
Dans ce cas, j'opterais pour une vérification des limites d'index et jetterais ma propre exception:
throw IllegalArgumentException("Index must be smaller than " +myClass.length + ", but is: " + index)
et puis documentez l'Exception IllegalArgumentException dans JavaDoc.
Nous avons une extension Checkstyle écrite qui s'exécute sur notre serveur de test. Dans votre échantillon, il testerait si HorribleException était documenté.
L'Exception ArrayIndexOutOfBoundsException détectera avec un examen de code. Dans votre exemple de code, nos objectifs devaient lancer une InvalidArgumentException à la place D'une ArrayIndexOutOfBoundsException. La documentation de celui-ci sera trouvée à partir du serveur de test.
L'Exception ArrayIndexOutOfBoundsException peut être un avertissement dans FindBugs. Mais je ne suis pas sûr.
La citation que vous avez posté, est juste quelque chose que vous devez garder à l'esprit si vous voulez être le programmeur idéal. La programmation ne pense pas "ce qui peut mal tourner", mais pense comment faire quelque chose de la meilleure façon et le programmer. Si c'est un projet personnel, écrivez simplement ce que fait la méthode.
Cependant, il existe trois solutions possibles:
- ne documentez pas la méthode.
- pensez à une minute de ce que fait votre code et découvrez quelles sont les exceptions non cochées les plus courantes pourrait être. Ajoutez-les au Java-doc. Et si vous en rencontrez un nouveau, Découvrez quel est le problème et ajoutez - le comme exception possible.
- Ne vous souciez pas des exceptions possibles et documentez uniquement les exceptions que vous jetez dans le corps de la méthode (comme:
if (obj == null) { throw new NullPointerException(); }).