Le Cool Auto Comment Tool de NetBeans 4.0 – Maintenant, documenter peut être marrant!

Cet article fait partie de la compet Win With NetBeans. Vous aurez le nom de l'auteur à la fin de la compétition. Il a été traduit par Philippe Vandenbulcke qui en refuse toute responsabilité.

Introduction

Désolé, le titre devait vous faire sourire, sinon vous ne liriez pas un article à propos de l'écriture de documentation.
J'ai toujours apprécié le JavaDoc Tool inclus dans le SDK par Sun; c'est une bonne méthode pour indiquer la bonne direction à de futurs développeurs/mainteneurs de votre code. Ou si vous êtes comme moi, de retrouver soi-même la bonne direction quand l'on a oublié comment marche le code après quelques mois/semaines/années.

En quoi l'Auto Comment Tool peut-il m'aider?

Ben, cela n'écrira pas la doc à votre place. Vous devrez toujours le faire, toutefois cela formattera/structurera vos commentaires d'une manière compatible JavaDoc.
Plus, et c'en est le clou, il indiquera les commentaires manquants. C'est une façon plus naturelle de valider vos commentaires Java. Avant d'employer Netbeans ou de découvrir l'Auto Comment Tool j'aurais lancé le JavaDoc Tool et modifié mes commentaires ou paramètres en fonction des avertissements reçus. Cette méthode bouffe du temps, est ennuyante et signifie une plus grande probabilité d'erreurs. Utiliser l'Auto Comment Tool vous signale de suite et sur place des erreurs ou omissions: Vous n'aurez plus à faire des allers retours entre le code et le rapport d'erreurs.

Comment employer l'Auto Comment Tool?

1. Ouvrir un projet Netbeans
2. Ouvrir un fichier Java ou sélectionner un fichier Java ou un Noeud de classe dans la fenêtre des projets. Sans cela, l'Auto Comment Tool n'est pas disponible. L'utilisation de l'Auto Comment Tool est basée sur les contextes. Lancer l'Auto Comment Tool sur une autre classe n'en ouvrira pas une autre instance. Cela implique qu'il n'y a moyen d'éditer les commentaires que d'un seul fichier java à la fois. Pas moyen de traiter tout un projet d'un coup! (suggestion pour amélioration)
3. Dans le menu tools choisir Auto Comment…

Une fois l'Auto Comment Tool ouvert, dans le panneau de gauche, vous trouverez une liste des méthodes de votre classe ainsi qu'une série de boutons avec icône.

Ces boutons sont des filtres. Si vous avez une classe avec un nombre élevé de méthodes et de variables, ces filtres vous aideront à focaliser sur rien que ce qui doit être commenté.

Utiliser les filtres d'Auto Comment

Pousez le premier bouton à gauche. Ce bouton ressemblera à une boîte verte avec une touche blanche. C'est une bascule. Quand ce bouton est activé, tous les commentaires aux normes java Doc sont montrés.

Pour avoir des explications plus complètes à propos des boutons filtre, voyez le menu Help, liste du contenu (help content). Choisissez y le volet de recherche et rentrez-y le mot-clef Auto Comment. Ou poussez simplement le bouton Help situé près de la liste des méthodes dans l'Auto Comment Tool.

Remarquez les icônes affichées à la suite de chaque méthode de la liste de votre classe, en-dessous des boutons des filtres.

Icône Commentaire Java OK

L'affichage de l'icône ressemblant à une boîte verte avec une touche blanche signifie que les commentaires pour cette méthode ou variable répondent aux normes JavaDoc et que vous n'avez rien d'autre à faire que de vérifier que vous avez introduit un commentaire adéquat/correct/à jour pour la variable ou méthode concernée.

Icône Commentaires Manquants

Si vous voyez une icône ressemblant à une boîte rouge munie d'un X blanc, cela signifie que le commentaire ne répond pas aux spécifications JavaDoc ou qu'il n'y a pas de commentaires associés. Lors de ma première utilisation de JavaDoc, j'ai quelques fois voulu écrire mes blocs de commentaire comme suit:

/*
* Java rocks
*/

Bien sûr, rien n'apparaissait dans la JavaDoc, car j'avais omis la double étoile. Si vous introduisez vos commentaires via l'Auto Comment dans le champ JavaDoc Comment text:, l'Auto Comment écrit vos commentaires dans le code avec une mise en page correcte, par exemple:

/**
* Java rocks

*/

Si l'erreur est l'absence de commentaire, Auto Comment vous le signale dans la zone de texte située sous la liste des méthodes au moyen du message JavaDoc comment is missing . Si vous avez déjà commenté la variable ou méthode et que cela affiche cette erreur, vous pouvez vérifier si vous n'avez pas omis la seconde * en poussant le bouton view source. A nouveau, comme tout le reste dans l'Auto Comment Tool, c'est basé sur le contexte: si vous n'avez pas de méthode sélectionnée, le bouton view source sera grisé et non fonctionnel.

Icône Erreur partielle ou Vous avez tout faux

L'icône la plus intéressante est un triangle traversé d'un éclair. Généralement, vous aurez ce signal quand vous omettez une balise @param alors que la méthode prévoit un paramètre. Auto Comment vous indiquera quel paramètre n'a pas sa balise. Par exemple: la balise pour le paramètre <Le nom de votre paramètre> manque.

Un autre exemple d'indication d'erreur partielle est quand vous ajoutez des balises superflues à un commentaire, par exemple si vous ajoutez la balise d'auteur à une méthode de classe et pas à la classe. Voir l'exemple ci-dessous:

 /**
 * This method does something
 * @param Something
 * @Author Jason Stapley – This is an error. Not me, the Author tag!
 */
Void doSomething(String Something) {
    System.out.println(Something);
}

Ce genre d'erreur peut être corrigé dan Auto Comment en sélectionnant la balise parasite dans la liste des balises et appuyant le bouton d'effacement. Ce qui nous permet de faire facilement la transition avec le sujet suivant, ajouter des balises.

Ajouter des balises à vos blocs de commentaires

Poussez le bouton new... sous la liste des balises dans l'Auto Comment Tool et la fenêtre des nouvelles balises apparaîtra. On y trouve les types de balises susceptibles d'être joints à votre bloc de commentaires. Les balises les plus communes sont @param et @return. Si vous avez une balise de paramètre, il faudra le nommer dans le champ paramètre. Ce paramètre doit correspondre à celui de votre méthode. Pas de panique, toute erreur sera signalée.

Ajoutez ensuite votre commentaire dans le champ Description . Répétez cela jusqu'à ce que tous vos paramètres et le retour soient commentés. Clickez sur une autre méthode ou sur refresh. La méthode juste traitée devrait recevoir l'icône Commentaire OK. Si ce n'est pas le cas, allez voir le message d'erreur qui vous est donné dans la zone de texte située en bas de la liste des méthodes pour connaitre la raison du problème.

Ordre des balises

Vous n'avez pas à mettre vos balises dans un ordre précis pour être admis par JavaDoc. Faites ce qui vous semble logique pour vous et aux lecteurs du code. En utilisant Auto Comment, vous pouvez modifier l'ordre des balises dans votre bloc de commentaires, par exemple si vous souhaitez que la balise retour soit toujours la dernière dans votre liste, vous devez la sélectionner et la faire descendre au moyen du bouton Move Down. Pour l'avoir en tête de liste, utilisez le bouton Move Up. Comme toujours, ces boutons dépendent du contexte d'utilisation.

balises HTML

Comme JavaDoc crée du HTML, vous pouvez utiliser des balises HTML dans vos commentaires. Sélectionnez la méthode ou un champ que vous désirez commenter et dans le champ JavaDoc Comment Text: , indiquez < et patientez une peu; une liste de balises utiles apparaîtra (Quand vous éditez votre code et ajoutez un point, une liste de méthodes est suggérée. Ceci fonctionne de la même façon pour les balises). Idem pour le champ Description.

Vous trouverez aussi une sélection des balises JavaDoc les plus courantes en bas à droite de l'écran de Auto Comment, à savoir <B> <I> <U> <CODE> <PRE> <@link>.

Très puissant.

Raffraîchir la fenêtre Auto Comment

Quelques fois il vous faudra retourner au code. Par exemple, quand vous avez omis une des deux étoiles pour démarrer le commentaire, vous serez condamné à corriger le code car Auto Comment ne peut les trouver. Si vous avez fait une erreur et que vous revenez, après sa correction, à la fenêtre Auto Comment, c'est toujours une bonne idée d'appuyer le bouton refresh, . Vous éviterez ainsi de faire deux fois le travail.

Correction Automatique

Soit une méthode avec beaucoup de paramètres dont la dactylographie prendrait un temps certain; la fonctionnalité Auto Correct pourra générer toutes les balises de paramètre et les nommer pour vous, ainsi vous n'aurez plus qu'à compléter les commentaires. Vous y parviendrez en sélectionnant la méthode à commenter et poussant le bouton Auto Correct, ajoutez ensuite vos commentaires dans le champ Description.

Quand Vous Avez Terminé

Assurez vous de sauvegarder votre dur labeur en poussant le bouton save all de la barre d'outils.

Conclusion

Maintenant que vous savez comment utiliser la fonctionnalité Auto Comment et combien de temps cela peut vous faire gagner, vous n'avez plus d'excuses pour ne pas commenter votre code. Faites l'expérience. Lancez le sur un vieux bout de code, vous m'en direz des nouvelles!!