Écriture de commentaires Java Doc pour les cas de tests unitaires

À mon avis, les cas de tests unitaires servent eux-mêmes de documentation pour le code. Mon entreprise veut que j'écrive des commentaires détaillés sur le doc java sur les tests élémentaires. Est-il nécessaire de le faire? Écrivez-vous des commentaires comme ça?

unit-testing documentation

— Vinoth Kumar CM
source

en supposant que le code de test est bien écrit et lisible, la valeur principale d'un commentaire de ce type dans le code de test est une déclaration d'intention. Cela peut être très précieux pour les réviseurs de code, même vous-même dans un an, car cela vous permet juger du code écrit, c'est faire ce qu'il est censé faire, ou tester ce qu'il est censé tester. Secondairement, vous pouvez utiliser des systèmes tels que JAVADOC ou même un simple script pour extraire les noms de test et les commentaires du code pour créer une documentation rapide sur les tests que vous avez et ce qu'ils font.

— Chuck van der Linden

Réponses:

Ce que je fais est un commentaire JAVADOC:

la classe, indiquant quelle classe est testée unitaire (même si cela devrait être évident car la meilleure pratique à ce sujet suggère que le nom du cas de test devrait être le nom de la classe + "Test" ou + "TestCase"). Cela se fait à l'aide du commentaire {@link XXXClass} JAVADOC
les méthodes, en indiquant la méthode testée ({@link XXXClass # method1}). Parfois, j'ai besoin de plusieurs méthodes de test pour une méthode d'une classe pour tester correctement tous les chemins. Lorsque cela se produit, j'écris une ligne supplémentaire indiquant le chemin que je teste à l'intérieur (mais je ne m'éloigne jamais de ma convention d'une ligne)

A part ça, pas d'autre commentaire. Pour attirer leur attention ailleurs, vous pourriez peut-être utiliser quelque chose comme Cobertura pour générer de jolis graphiques de couverture de code et les rendre heureux de cette façon :-)

Note supplémentaire: je fais référence aux cas de tests unitaires, si nous parlons de cas de tests d'intégration, alors une ou deux lignes supplémentaires pour expliquer ce qui se passe peuvent en effet être nécessaires ...

— Jalayn
source

Les exigences de documentation pour tout code sont assez complètement couvertes dans les réponses à cette question: Mon patron veut une explication narrée ligne par ligne de notre code

Pour résumer les réponses que vous y verrez, "Cela dépend de votre situation". Il y a des cas où c'est raisonnable (et encouragé), et d'autres où c'est une perte de temps.

— blueberryfields
source

Les commentaires Javadoc peuvent être extraits et formatés dans un document de référence distinct, contrairement aux tests unitaires. Gardez également à l'esprit que ce que vous écrivez en mots peut être différent du code réel et que vous décrivez généralement en mots le comportement réel attendu. L'une des façons de trouver des bogues est de comparer la documentation au code réel, s'ils ne correspondent pas - c'est un bogue (dans l'un ou l'autre, et parfois - dans les deux).

Le test unitaire sert à tester, pas à documenter. Utiliser le test unitaire comme documentation est faux et ne devrait pas être fait.

— littleadv
source

Je trouve une bonne suite de tests unitaires extrêmement utiles pour documenter le code. Ils fournissent une implémentation de référence sur la façon dont le code d'une personne doit être utilisé, ainsi que la preuve que le code se comporte correctement lorsqu'il est utilisé de cette façon.

— Bill Michell

@Bill - aucun argument là-dessus, c'est utile. Il ne remplace pas une documentation appropriée.

— littleadv

Cela dépend du public pour votre documentation - mais dans certains cas, vous avez certainement raison.

— Bill Michell

Idéalement , les tests unitaires ne devraient pas être la seule documentation d'un système - mais dans le monde réel, 9 projets sur 10 fonctionnent avec du code hérité où il peut être considéré comme chanceux d'avoir une quelconque documentation. Et dans ce cas, je préfère un bon ensemble de tests unitaires en cours d'exécution et de réussite à un tas de documents qui peuvent être totalement désynchronisés avec le code réel. (Oui, même le Javadoc le peut.)

— Péter Török

@ PéterTörök Ouais ... J'ai déménagé entre plusieurs employeurs différents, des entreprises très connues. Beaucoup de code hérité. Les seuls tests unitaires jamais réalisés - ceux que j'ai écrits. Vous avez donc été très très chanceux. Ne présumez pas que ce que vous avez vu est ce qui se passe partout. Et même si vous avez un ensemble de tests unitaires ... Qui a dit qu'ils étaient corrects? Qui a dit qu'ils couvraient ce qu'ils devraient? Qui a dit que les résultats attendus sont ce qu'ils sont? Pourquoi supposez-vous que les tests unitaires ne sont pas désynchronisés? Tout simplement parce qu'ils "passent"? Absurdité.

— littleadv