Le style RPG IV revisité

Un bon style de programmation aide
autrui à  comprendre votre code source. Si vous adoptez de bonnes
techniques de construction de code,
vous constaterez que « moins est plus »
en matière de commentaire du code
source. Il est aussi mauvais d’avoir trop
de commentaires que d’en avoir trop
peu. Voici quelques conseils concernant
les commentaires.

Utilisez les commentaires pour
clarifier le code, pas pour le répéter
en écho. Les commentaires qui se
contentent de répéter le code augmentent
la taille d’un programme mais
pas sa valeur. En général, les commentaires
doivent se limiter à  trois objectifs
:

• fournir un résumé du programme ou
de la procédure

• donner un titre à  une sous-routine,
procédure, ou autre section de code

• expliquer une technique qui n’apparaît
pas clairement à  la simple lecture
du code source

Placez toujours un bref résumé au
début d’un programme ou d’une
procédure. Ce prologue doit inclure
les informations suivantes :

• 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
incluant la date, le nom du programmeur,
et l’objet de chaque modification

• un résumé de l’usage des indicateurs

• une description de l’interface de procédure (la valeur de renvoi et des paramètres)

• un exemple du mode d’appel de la
procédure

Utilisez des commentaires de
type « ligne de marquage » pour diviser
les principales sections du code.
Par exemple, il faut séparer par des
lignes de tirets (-) ou d’astérisques (*)
les déclarations, la procédure principale,
chaque sous-routine, et les éventuelles
sous-procédures. Repérez
chaque section pour faciliter les références.

Utilisez des lignes vierges pour
grouper des lignes source associées
et pour les mettre en valeur. En général,
utilisez des lignes complètement
vierges au lieu de lignes de commentaires
vierges pour grouper des lignes
de code, sauf si vous construisez un
bloc de commentaires. Mais tenezvous
en à  une seule ligne vierge ; de
multiples lignes vierges consécutives
rendent le programme difficile à  lire.

Evitez des commentaires « fin de
ligne » à  droite dans les colonnes 81
à  100. Les commentaires de droite
tendent simplement à  répéter le code
en écho, risquent d’être perdus pendant
la maintenance du programme, et
peuvent facilement se désynchroniser
de la ligne qu’ils commentent. Si une
ligne source est suffisamment importante
pour justifier un commentaire,
celui-ci mérite une ligne distincte. Le
support de la version 5 pour les commentaires
de fin de ligne (en commençant
par //) assouplit un peu cette
règle, mais si le commentaire ne fait
que répéter le code, éliminez-le.