Dans le cadre de mon nouvel emploi, j'ai découvert un outil très pratique : Ghost Doc.
Cet add-in gratuit pour Visual Studio aide les développeurs à créer de la documentation pour leur code. Il suffit de positionner le curseur sur le nom d'une méthode ou d'une propriété et de taper un raccourci clavier (Ctrl+Shift+D par défaut), et Ghost Doc génère automatiquement un bloc de commentaire XML Doc.
La beauté de Ghost Doc est la façon dont il génère ces commentaires. Si vous documentez une méthode que vous implémentez d'une interface ou d'une super classe, la documentation existante sera copiée pour votre implémentation. Si toutefois vous documentez une nouvelle méthode, le commentaire sera généré à partir du nom de la méthode. Par exemple, avant :
public void ChangeDirectory(string targetDirectory)
{
}
Et après :
/// <summary>
/// Changes the directory.
/// </summary>
/// <param name="targetDirectory">The target directory.</param>
public void ChangeDirectory(string targetDirectory)
{
}
À première vue, ceci ne semble peut être pas si utile. Peut-être que vous n'utilisez pas les commentaires XML Doc présentement, et que vous ne voyez pas pourquoi vous utiliseriez un tel outil. Demandez-vous dans ce cas : pourquoi n'utilisez-vous pas XML Doc? La réponse est probablement : parce que c'est trop long à écrire! Et bien, avec Ghost Doc, vous n'avez plus d'excuse! Bien entendu, certaines méthodes demandent quelques ajustements aux commentaires générés, mais comme toute la base du commentaire a déjà été générée pour vous, il est très facile de faire les modifications nécessaires.
Un autre avantage de Ghost Doc que j'ai remarqué est qu'à force de l'utiliser, on apprend à mieux nommer ses méthodes. Après avoir bien compris comment les commentaires sont générés, il deviens naturel de choisir un bon nom pour une méthode afin que le commentaire généré soit le plus clair possible, sans avoir à le modifier manuellement. Ce n'est pas évident à expliquer, mais on comprend bien à force de l'utiliser.
Finalement, plusieurs options de configuration sont disponnibles, permettant ainsi d'ajouter certains mots ou certains types de méthodes pour lesquels des traitements spéciaux sont nécéssaires.
J'utilise cet outil depuis maintenant quelques jours, et déjà, je ne m'en passerais plus! Je vous suggère fortement d'en faire l'essaie!
