Comment documenter les scripts dans Unity?

Les commentaires dans les scripts sont importants pour expliquer leur fonctionnement. L'utilisation des commentaires varie d'une école de pensée à une autre. Certains prônent l'utilisation massive de commentaires pour expliquer les intentions du code. D'autres croient que le code devrait être auto explicatif et libre de commentaires. Ma position sur le sujet est mitoyenne. J'utilise des noms de fonctions et de variables évocatrices, claires et indiquant leur fonction le plus souvent possible. Malgré tout, si je ne commente pas régulièrement, j'ai de la difficulté à saisir mon propre code après quelques mois. Alors, je documente.

L'ajout d'un commentaire se fait en ajoutant deux barres obliques "//":

//Un commentaire vraiment inutile.
string action = "Commente moi!"

ou pour un bloc de commentaires, avec "/*" et "*/":

/*
Il était une fois, dans l'ouest, une princesse prisonnière
dans une taverne miteuse gardée par des truands à la peau
tannée par le soleil et au regard sauvage, etc., etc., etc.
*/
string action = "Commente, mais commente égal!"

et aussi avec "///":

///Parce que // fait tellement 1990.
string action = "Commente moi!"

Dans MonoDevelop, si vous tapez "///" avant une entité (une variable, une fonction, une classe, etc.) vous obtenez:

/// 

/// Du XML???
/// 
private string action = "Commente moi!" 

MonoDevelop crée un commentaire avec un tag XML. Ce code XML est utilisé par un programme externe pour générer automatiquement la documentation. Les générateurs de documentation sont des programmes qui lisent le code source et les commentaires, l'analysent et retournent une documentation en format texte, HTML, XML, Latex, etc. qu'il est possible de consulter et d'effectuer des recherches. C'est très pratique pour se retrouver dans un gros projet avec des centaines de scripts. Mon générateur de documentation favori est Doxygen. Je vais parler de Doxygen dans un prochain billet.

L'utilisation du système de documentation avec l'XML amène un autre énorme avantage, en plus de la génération automatique de la documentation. Si vous glisser votre souris au-dessus d'une entité du code (une variable, une fonction, un enum, etc.), une info bulle jaune apparaît qui ressemble à ceci:

L'information de cet encadré n'est pas très utile. Nous apprenons que _selected est un booléen. Avec l'ajout d'un commentaire XML, voici le résultat:

Notre commentaire apparaît dans l'info bulle jaune! Cette description va apparaître si le curseur glisse au-dessus de la variable _selected quel que soit sa position dans le code. Si une variable publique est commentée, la description va aussi apparaître si la variable est utilisée dans une autre classe. Ce petit encadré peut sauver du temps. Imaginer que vous êtes dans le code. Vous travaillez sur une fonction, mais vous ne vous souvenez plus de l'intention d'une fonction ou de ce que stocke une variable. Normalement, vous naviguez dans le code, allez à la fonction ou à la variable, lisez la description et revenez à votre fonction. C'est long et inutile. Avec les commentaires XML, glisser le curseur sur la variable ou la fonction mystérieuse et voilà la description (si bien sur vous l'avez documentée).

Les commentaires en XML sont plus longs que les commentaires normaux, mais je recommande de les utiliser systématiquement pour permettre de générer la doc automatiquement et pour les info bulles. La longueur des commentaires n'est pas un problème réel avec les éditeurs modernes. Mono Develop permet de cacher les commentaires en appuyant sur le symbole +:

Avant.

Après.

Peu importe la longueur du commentaire, une fois refermé, il ne prendra qu'une ligne, vous permettant de lire le code sans obstruction.