Tous les langages de programmation offrent la possibilité d'insérer dans le texte du programme des messages destinés exclusivement au lecteur du programme (le compilateur ne les regarde même pas). Ce sont des commentaires.
Il est courant de croire que la lisibilité d'un programme augmente avec le nombre de lignes de commentaires. Ceci est faux en général.
D'abord, il faut comprendre que le contenu des commentaires n'est en aucun cas vérifiable par le compilateur. La cohérence entre commentaires et programme est donc à la responsabilité du programmeur. Et comme à chaque fois qu'un humain est responsable, des erreurs peuvent se produire. En l'occurrence, le programmeur doit veiller à ce que les commentaires soient conformes au code commenté. Dans la première version d'un programme, c'est relativement facile. Puis, lorsque le programme est modifié, c'est de plus en plus difficile. Souvent le code est modifié sans que le commentaire du code soit mis à jour. Le résultat est une situation (malheureusement assez fréquente) où le code et le commentaire ne correspondent pas.
Pour éviter ce type de problème, nous conseillons d'éviter les commentaires redondants , à savoir les commentaires qui n'ajoutent pas vraiment de compréhension supplémentaire du code. Un cas spécial et malheureusement assez fréquent de ce type de commentaire sont les paraphrases. Il s'agit de commentaires qui répètent (en anglais ou en français) la signification immédiate du code.
Exemples :
i = 0 # set i to zero i = i + 1 # increment i
Ce type de commentaire est donc à éviter.
Un autre type de commentaire redondant (malheureusement souvent pratiqué dans le développement professionnel) est le commentaire de fonction. Ce type de commentaire précède une fonction ou une procédure, et explique le nom de la fonction, le nombre et le nom des arguments, etc. En général, ce type de commentaire fait bonne impression. Malheureusement, il est aussi source de confusion. Si jamais le nombre d'arguments de la fonction change, le commentaire devient automatiquement faux. Le développeur doit alors vérifier manuellement la cohérence entre le code et le commentaire.
Quels sont donc les commentaires souhaitables? C'est relativement simple. Un commentaire est souhaitable lorsque il facilite la lecture du programme par le mainteneur. Avant d'écrire un commentaire, il faut donc se mettre à la place d'un lecteur potentiel et vérifier que sa tâche en sera réellement simplifiée.
Les commentaires sont un complément au code. En aucun cas un commentaire n'est destiné à un lecteur incapable de comprendre le code même.