Utiliser les commentaires à  bon escient

Voici quelques conseils en matière de commentaires.

Utiliser des commentaires // exclusivement. Désormais, les commentaires du RPG IV commencent par deux barres obliques (//) au lieu de l’astérisque traditionnel (*) en colonne 7. En format libre, le code n’autorise pas le format astérisque et le commentaire peut commencer n’importe où à partir des colonnes 8 à 80, et peut même se trouver sur la même ligne que les instructions exécutables.

Le nouveau format de commentaire peut aussi remplacer les commentaires astérisque dans des spécifications en format fixe, mais le commentaire doit occuper une ligne à lui tout seul. Par souci d’homogénéité, utilisez exclusivement le nouveau format, même dans des spécifications en format fixe (figure 6).

Utiliser des commentaires pour clarifier le code, pas pour le répéter Des commentaires qui se contentent de répéter le code alourdissent un programme sans le bonifier. En général, les commentaires doivent avoir trois buts :

• fournir un bref résumé du programme ou de la procédure
• donner un titre à une sous-routine, une procédure, ou autre section de code
• expliquer une technique qui n’apparaît pas à la seule lecture du code source

Inclure toujours un bref résumé au début d’un programme ou d’une procédure.Ce prologue doit contenir l’information suivante :

• le titre du programme ou de la procédure
• une brève description de l’objet du programme ou de la procédure
• une chronologie des changements : date, nom du programmeur, et raison de chaque changement
• un résumé de l’utilisation des indicateurs
• une description de l’interface de procédure (la valeur de renvoi et les paramètres)
• un exemple de la manière d’appeler la procédure

Utiliser des commentaires « ligne de marquage » homogènes pour diviser les principales sections de code. Par exemple, il faut séparer clairement par des lignes de tirets (-) les déclarations, la procédure principale, chaque sous-routine, et les éventuelles sousprocédures. Identifiez chaque section pour qu’il soit plus facile de s’y référer.

Utiliser des lignes vierges pour grouper des lignes source de même nature et pour les mettre en exergue.En général, utilisez des lignes complètement vierges plutôt que des lignes de commentaires vierges pour grouper des lignes de code, sauf si vous construisez un bloc de commentaires. Mais n’utilisez qu’une ligne vierge : plusieurs lignes vierges consécutives rendent le programme difficile à lire.

Eviter des commentaires « fin de ligne » à droite dans les colonnes 81 à 100.Les commentaires à droite ont tendance à répéter simplement le code. Il est facile de les perdre pendant la maintenance du programme et ils peuvent facilement se désynchroniser de la ligne qu’ils commentent. Donc, n’utilisez pas de commentaires à droite dès lors que les commentaires peuvent être alignés avec le code.