Commentaires

En Common Lisp, un commentaire commence par le caractère `;' et se termine par la fin de la ligne. Mais la communauté des programmeurs Common Lisp donne une signification au nombre de caractères `;' qui commencent le commentaire. Voici la règle à utiliser :

• un seul caractère `;' est utilisé pour les commentaires concernant une seule expression ; ce commentaire doit succéder l'expression sur la même ligne de texte. Le commentaire doit être très bref, quelques mots seulement.
• deux caractères `;' sont utilisés pour les commentaires plus conséquents concernant peu d'expressions à l'intérieur d'une fonction. Le commentaire ne doit pas dépasser quelques lignes, doit précéder les lignes de code concernées et doit être indenté autant que ce code.
• trois ou quatre caractères `;' sont utilisés pour des commentaires concernant une fonction (ou une autre définition) entière, voire plusieurs. Ces commentaires débutent toujours en première colonne et peuvent être assez conséquents (plusieurs dizaines de lignes).

Un commentaire est un complément du code. Le lecteur des commentaires doit être aussi capable de comprendre le code. Les commentaires sont supprimés par le compilateur. Celui-ci ne peut donc pas vérifier leur contenu. Il est toujours préférable de produire du texte vérifiable par le compilateur, si on en a le choix. Par conséquent, si le programmeur a le choix entre expliquer son code avec un commentaire ou bien réécrire le code pour qu'il soit plus lisible, il doit préférer la réécriture.

Mettre un commentaire est donc la solution ultime (quand aucune autre ne fonctionne) pour expliquer le code. Un commentaire concernant un code qui est déjà clair pose lui-même un problème. Durant la maintenance du programme, il arrive fréquemment (par manque de temps sans doute) que le code soit modifié mais pas le commentaire associé. Le résultat est un programme dont les commentaires ne reflètent plus le code. Donc il faut éviter les commentaires inutiles.

Un cas particulier de commentaire inutile est le commentaire paraphrase du code. Il prend du temps à taper et ne sert à rien. Voici quelques exemples de ce type de commentaire (donc à ne pas écrire) :

(incf x) ; increment x
(aref v i) ; get the i:th element of v
(f x y z) ; call f with arguments x, y and z

Pour commenter une fonction ou autre définition, faire un commentaire bref. Souvent, un identificateur bien choisi permet d'éviter un commentaire. Il faut éviter de répéter les noms et les types des paramètres dans le commentaire si ces informations sont déjà présentes dans l'en-tête de la définition. et éviter aussi des mots sans signification comme ``this function''. En Common Lisp, il est préférable de découper le code en petites fonctions dont le fonctionnement est évident, plutôt que de maintenir de grosses fonctions nécessitant une explication sous forme de commentaires.