Règles de formatage et conventions d'écriture

REGLES DE FORMATAGE ET CONVENTIONS D'ECRITURE

Comme nous l'avons-vu précédemment, il est très facile d'écrire un programme illisible ou très structuré. Pour vous aider lors de la rédaction de vos programmes, voici les quelques règles que j'essaie de respecter lors de l'écriture de programmes:

IDENTIFICATEURS

MOTS RESERVES ET IDENTIFICATEURS PRE-DECLARES: Les mots réservés du langage (BEGIN, END, FOR, DO, ...) ainsi que tous les identificateurs prédéclarés (INTEGER, BYTE, CHAR, ...) sont écrits en majuscules.
CONSTANTES: Les identificateurs de constantes sont composés de minuscules uniquement. Les différents mots sont éventuellement séparés des "underline". Exemples: dimension_tableau, blanc, tva, ...
VARIABLES: Les identifiants de variables sont écrites en minuscules avec les initiales en majuscule. Les mots sont éventuellement séparés par des "underline". Exemples: Age_Du_Capitaine, Couleur_Fond_Ecran, Vitesse, Acceleration, ...
TYPES: Les identificateurs de type commencent toujours par "T_" puis sont écrits comme les variables, en minuscules avec des initiales en majuscules. Exemples: T_Couleur, T_Genre, T_Code_D_Erreur, ...
PROCEDURES: Les identificateurs de procédures sont écrits comme les noms des variables en minuscules avec des initiales en majuscules.Mais on utilisera un verbe à l'infinitif, car un appel de procédure décrit une action à réaliser: Afficher, Close, Effacer_Ecran, Rebedouler, ...
FONCTIONS: Les identificateurs des fonctions sont écrits comme les noms des variables en minuscules avec des initiales en majuscules.A l'inverse des procédures, un nom (ou une locution) sera utilisé pour l'identification, car un appel de fonction décrit le résultat d'une action à réaliser. Exemples: Caractere_Lu, Sinus_Hyperbolique, ... En principe, une fonction ne devrait avoir qu'un seul paramètre de sortie: le résultat de la fonction. Si une routine doit avoir plusieurs paramètres de sortie, il est préférable d'utiliser une procédure.
UNITES ET PROGRAMME PRINCIPAL: Les identificateurs d'unités ou de programme principal sont également écrits comme les noms de variables en minuscule avec initiales en majuscules.

DECLARATIONS

Autant que possible, on ne déclarera qu'un objet par ligne (constante, type ou variable) afin de pouvoir commenter chacun de ces objets sur la même ligne. Exemple:

CONST
max_x = 100;                          { Bla Bla Bla }
max_y = 200;                          { Patati Patata }

TYPE
T_Couleur = (rouge, vert, bleu);       { Pfffffrrrt }
T_Truc = [39..45];                     { Tagada... }
T_Chose = RECORD                       { ...Tsoin tsoin }
              Zorglad_Gauche : INTEGER;
              Cameleo : T_Couleur;
            END; {RECORD}

VAR
I,                                     { Voilà voilà }
J,                                     { Ca nous rajeunit pas }
K,                                     { K comme Koala }
Longueur : INTEGER;                    { En angström }
Tableau : ARRAY [1..max_c, 1..max_y] OF BYTE;

INDENTATION

Un incrément d'indentation de 2 caractères sera utilisé à chaque niveau

BOUCLES FOR, WHILE ET REPEAT: Ces boucles sont présentées de la manière suivante:

Statment;
Statment;
FOR I := 1 TO 10 DO BEGIN
Statment;
Statment;
END; {FOR}
Statment;
Statment;
WHILE X < Y DO BEGIN
Statment;
END; {WHILE}
Statment;
Statment;
REPEAT
Statment;
UNTIL X > Y;
Statment;

On commentera les END de façon à indiquer à quelle boucle ils appartiennent. On placera également un ";" après la dernière instruction de la boucle (juste avant le END). de façon à faciliter d'éventuelles insertions d'instructions ultérieures.
INSTRUCTIONS IF ET CASE: Par analogie, l'indentation des instructions IF est CASE est la suivante:

Statment;
Statment;
IF Condition THEN BEGIN
Statment;
END; {IF}
Statment;
IF Condition THEN BEGIN
Statment;
END {IF}
ELSE IF Condition2 THEN BEGIN
Statment;
Statment;
END {ELSE IF}
ELSE BEGIN
Statment;
END; {ELSE}
Statment;
Statment;

Statment;
Statment;
CASE Couleur OF
rouge : BEGIN
            Statment;
            Statment;
          END; {BRANCH OF CASE}
vert : BEGIN
            Statment;
            Statment;
          END; {BRANCH OF CASE}
ELSE    BEGIN
            Statment;
            Statment;
          END; {OTHERWISE}
END; {CASE OF}
Statment;
Statment;

Il faut noter que chaque END est accompagné d'un commentaire indiquant à quel BEGIN il appartient. Cela est fort utile lorsqu'il y a plusieurs boucles imbriquées les unes dans les autres...
De plus, même s'il n'y a qu'une seule ligne dans le IF THEN ou le CASE, il y a toujours un BEGIN..END, afin de faciliter l'insertion ultérieure de quelques nouvelles lignes de code.

Pour terminer cette théorie, voici deux listings de la même procédure. Lequel des deux trouvez-vous le plus agréable à lire ?

Type
tTableau=Array[1..100] Of Real;

Procedure MaxMin(T:tTableau;
              Var max, min: Real);
Var i : Integer ;
Begin
  max := T [ 1 ] ;
  min := T [ 1 ] ;
  For i := 2 to n Do
    If T [ i ] > max Then
      max := T [ i ]
    Else If T [ i ] < min Then
      min := T [ i ]
End;

TYPE
tTableau=Array[1..100] OF REAL;

PROCEDURE MaxMin(T:tTableau;
              VAR max, min:REAL);
VAR
i : INTEGER;
BEGIN
max := T[1];
min := T[1];
FOR i := 2 TO n DO BEGIN
    IF T[i] > max THEN BEGIN
      max := T[i];
    END {IF}
    ELSE IF T[i] < min THEN BEGIN
    min := T[i]
    END; {ELSE IF}
END; {FOR}
END; {PROCEDURE MaxMin}

Question subsidiaire, que fait cette procédure ?