Documenter son code .NET avec GhostDoc

Bien documenter son code est important afin d’aider d’une part d’autres développeurs à comprendre le code le plus rapidement possible mais aussi à soi-même afin d’être le plus efficace possible lors de la maintenance du code.

Visual Studio utilise le XML pour ses commentaires, pour par exemple ajouter une description à une méthode.

/// <summary>
/// Tests the specified param1.
/// </summary>
/// <param name="param1">The param1.</param>
/// <param name="param2">The param2.</param>
/// <param name="param3">The param3.</param>
/// <param name="param4">The param4.</param>
/// <returns>This method return 1</returns>
public int Test(int param1, int param2, int param3, int param4)
{
    return 1;
}

Si l’application fait plusieurs milliers de lignes, il est long et fastidieux de documenter chaque méthode, classe, etc… Souvent la quantité se fait au détriment de la qualité. Pour remédier à cet obstacle et toujours garder un code correctement documenté, il est possible d’utiliser un outil nommé GhostDoc. **GhostDoc **s’intègre à Visual Studio (de 2005 à 2010) et génère via un raccourci clavier (Ctrl-Shift-D par défaut) la documentation d’une méthode, classe, etc… Seule condition, respecter quelques standards de nommage dans votre code. Par exemple “myParam” pour un paramètre et “DefineTheParam” pour une méthode. En effet GhostDoc va découper les noms de paramètres, méthodes, etc… afin de construire des phrases dans la documentation.

Pour utiliser GhostDoc, séléctionner l’entité (méthode, classe, etc…) et faire Ctrl-Shift-D pour générer la documentation.

Ainsi la méthode :

public void DefineTheSentence(string sentenceToDefine)
{
}

générera la documentation :

/// <summary>
/// Defines the sentence.
/// </summary>
/// <param name="sentenceToDefine">The sentence to define.</param>

**GhostDoc **offre la possibilité d’ajouter des règles à appliquer pour certaines méthodes, classes, etc… Il est par exemple possible de rajouter son nom dans toutes les documentations des classes ou seulement de certaines méthodes contenant par exemple le mot “Private”.

Ces modifications se réalisationt via le menu Tools > GhostDoc > Configure GhostDoc

Cliquer sur une catégorie puis sur _Add _pour ajouter une nouvelle règle.

Dans l’exemple suivant, toutes les classes qui ont un nom contenant le mot “Private” auront le nom du propriétaire dans la description.

Cliquer sur type name <any>

Il est possible de tester la condition. Ici MyPrivateClass correspond à notre condition. Cliquer sur OK.

A côté de <summary>, cliquer sur le bouton contenant les …

Ajouter $(Environment.UserName) dans Template Text pour ajouter le nom du propriétaire de la classe.

Cliquer successivement sur OK pour enregistrer la règle.

Désormais, lorsque **GhostDoc **rencontrera une classe contenant “Private”, la documentation contiendra le nom du propriétaire.

Exemple :

class MyPrivateClass
{
}

aura pour documentation

/// <summary>
/// Aymeric
/// </summary>

Astuce : Si un changement est fait dans le code (changement de nom, des paramètres, etc…), sélectionner simplement le nom de la méthode (classe, interface, etc…) et faite Crtl-Shift-D pour re-générer la documentation.