next up previous contents index
Next: Portée des identificateurs Up: Lisibilité Previous: Choix des identificateurs   Contents   Index

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 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.


next up previous contents index
Next: Portée des identificateurs Up: Lisibilité Previous: Choix des identificateurs   Contents   Index
Robert STRANDH
2001-09-28