La documentation du code
Documenter un code pour celui qui le reprendra : commentaires de documentation Javadoc et leurs balises, commentaires qui disent pourquoi, README, documentation générée.
- 26 cartes
- 5 thèmes
- Gratuit
Le programme, thème par thème
Le poids de chaque thème suit celui que lui donne l'examen.
- Notions
- Questions
- Ranger et relier
- Mises en situation
- Comprendre
Quelques cartes du deck
Commentaire de documentation : de quoi s'agit-il ?
Voir la réponse
Commentaire placé juste avant une classe ou une méthode, écrit dans une forme que des outils savent lire pour produire la documentation du code.
En Java il s'ouvre par
/**. Il décrit le contrat de la méthode (ce qu'elle attend, ce qu'elle renvoie) pour celui qui l'appelle sans lire son corps.L'outil javadoc affiche l'erreur ci-dessous. Quelle correction faut-il apporter ?
```java
Rem.java:5: error: @param name not found
/**
* Applique une remise.
* @param prix le prix
* @param taux le taux
* @return le prix remisé
*/
public static double appliquer(double prix, double remise)`- Renommer la balise en @param remise, comme dans la signature
- Ajouter à la méthode un troisième paramètre nommé taux, pour que la balise corresponde
- Supprimer la balise @return, qui ne devrait pas figurer ici
- Ajouter une balise @throws avant celle du paramètre en cause
Voir la réponse
Renommer la balise en @param remise, comme dans la signature
La documentation a gardé l'ancien nom du paramètre. Javadoc compare les balises à la signature, d'où l'erreur ; il signale aussi le manque :
warning: no @param for remise.Un bon commentaire dit … le code fait ce choix ; ce que fait la ligne, le code le dit déjà par ses ….
Voir la réponse
Un bon commentaire dit pourquoi le code fait ce choix ; ce que fait la ligne, le code le dit déjà par ses noms.
Un commentaire qui paraphrase la ligne doit être maintenu en même temps qu'elle et finit par la contredire. Mieux vaut un nom de variable ou de méthode plus clair.
Javadoc : de quoi s'agit-il ?
Voir la réponse
Outil du JDK qui lit les commentaires de documentation d'un code Java et en génère des pages HTML, en signalant les balises erronées.
Il vérifie la cohérence avec la signature : une balise
@parampour un paramètre qui n'existe pas donne l'erreur@param name not found.La description des méthodes d'une bibliothèque Java, tenue dans un document à part, contredit le code depuis des mois. Que faire ?
- Relire le document de bout en bout chaque année et corriger tous les écarts les plus importants trouvés
- Supprimer le document et ne plus rien écrire sur le fonctionnement
- Demander aux utilisateurs de signaler les erreurs qu'ils rencontrent
- La mettre dans des commentaires au-dessus des signatures et la générer à chaque construction
Voir la réponse
La mettre dans des commentaires au-dessus des signatures et la générer à chaque construction
Une documentation vit au plus près du code qu'elle décrit : celui qui modifie une signature voit le commentaire et l'outil signale les balises périmées. La documentation générée est ainsi recalculée à chaque fois.