Commentaires au niveau des fonctions

Voici un format que je vous suggère pour les commentaires d'en-tête au niveau des fonctions/procédures dans vos programmes, ainsi que des explications.Veuillez noter que je vous suggère ça parce que c'est une bonne pratique et non pas parce que le prof m'a demandé de le faire. Donc la morale de l'histoire est : faites-en ce que vous en voulez.

-- Fonction    : Nom de la fonction/procédure
-- Description : Brève description de ce que la fonction/procédure fait.
-- Entrées     : Description des paramètres IN et IN OUT tels qu'ils doivent être à l'entrée.
-- Sorties     : Description des paramètres OUT et IN OUT tels qu'ils doivent être à la sortie.
-- Retour      : Description de la valeur de retour (si c'est une fonction).
-- Pré         : Pré-conditions (antécédents).
-- Post        : Post-conditions (conséquents).

1. Qu'est-ce qu'une fonction (ou procédure)?

Une fonction (ou procédure) devrait être vue comme une "boîte noire". En principe, cette boîte noire ne devrait communiquer avec l'extérieur que par ses paramètres et ses valeurs de retour. On dira alors qu'elle est étanche.

2. Qu'est-ce que des pré-conditions et pourquoi en mettre?

Il s'agît de conditions écrites sur la boîte noire qui doivent être respectées par celui qui emploie la boîte s'il veut qu'elle fasse ce qu'elle dit qu'elle fait dans la description de ses fonctionnalités. On met ce genre de condition pour dire à celui qui utilise la fonction/procédure : "vérifie si toutes les conditions sont respectées avant de m'appeler sans quoi je ne réponds pas de mes actions". À l'opposé, ça veut aussi dire : "je te garantis que si tu respectes ces conditions, le résultat que tu obtiendras en m'appelant sera conforme à ce que je t'ai annoncé dans ma description".

3. Qu'est-ce que des post-conditions et pourquoi en mettre?

Il s'agît de conditions écrites sur la boîte noire qui décrivent dans quel état le système est laissé lorsque la fonction/procédure termine son exécution (on appele ça des effets de bord). On met des post-conditions pour dire à l'utilisateur de la fonction/procédure : "à la fin de mon travail, il y aura des choses qui se sont passées et que tu ne verras pas directement dans les paramètres/valeur de retour et qui ne sont pas évidentes quand on regarde ma description" (par exemple, un fichier laissé ouvert).

4. Exemples

Exemple 1 : Prenons l'exemple d'une procédure qui prend en entrée un fichier logique ainsi qu'un numéro d'enregistrement, qui lit l'enregistrement dans le fichier, et qui le retourne. Supposons que les enregistrements sont des produits. On aurait un commentaire au niveau de la procédure du genre :

-- Fonction    : LireProduit
-- Description : Lit un produit dans un fichier puis le retourne.
-- Entrées     : fic -> Fichier logique de produits.
--               num -> Numéro du produit à lire.
-- Sorties     : enr -> Le produit lu.
-- Retour      : Aucun.
-- Pré         : - Le fichier 'fic' doit avoir été ouvert au préalable.
--               - La valeur 'num' doit être <= au nombre de produits dans le fichier 'fic'.
-- Post        : - Le filepointer du fichier 'fic' sera positionné au produit 'num' + 1.
PROCEDURE LireProduit(fic : FichierProduits; num : Positive; enr : OUT T_Produit) IS BEGIN
...
END LireProduit;

Exemple 2 : Prenons l'exemple encore plus simple d'une fonction qui convertit une température Celsius en température Farenheit ou vice-versa. On aurait un commentaire au niveau de la fonction du genre :

-- Fonction    : ConvertirTemp
-- Description : Conversion d'une température Celsius en température Farenheit ou vice-versa.
-- Entrées     : temp -> La température à convertir.
--               conv -> 'C' pour convertir en Celsius, 'F' pour convertir en Farenheit.
-- Sorties     : Aucune.
-- Retour      : Température convertie.
-- Pré         : 'conv' doit avoir la valeur 'C' ou 'F'.
-- Post        : Aucune.
FUNCTION ConvertirTemp(temp : Float; conv : Character) RETURN Float IS BEGIN
...
END ConvertirTemp;

Note : Dans cet exemple, on aurait pu éviter la pré-condition en se créant un type énuméré et en imposant que le paramètre 'conv' soit de ce type. De cette façon, il aurait été impossible de passer des valeurs invalides à la fonction dans le paramètre 'conv' puisque le compilateur ne l'aurait pas laissé passé. Par exemple :

TYPE T_UniteTemperature IS(Celsius, Farenheit);

...

-- Fonction    : ConvertirTemp
-- Description : Convertir une température Celsius en température Farenheit ou vice-versa.
-- Entrées     : temp -> La température à convertir.
--               conv -> Vers quelle unité de température la conversion se fera.
-- Sorties     : Aucune.
-- Retour      : Température convertie.
-- Pré         : Aucune.
-- Post        : Aucune.
FUNCTION ConvertirTemp(temp : Float; conv : T_UniteTemperature) RETURN Float IS BEGIN
...
END ConvertirTemp;

Exemple 3 : Prenons l'exemple d'une fonction utilitaire pour lire une valeur réelle dans une plage donnée au clavier, et qui ne rend pas le contrôle tant qu'une valeur valide n'a pas été entrée. On aurait un commentaire au niveau de la fonction du genre :

-- Fonction    : LireReel
-- Description : Fonction utilitaire qui demande à l'usager d'entrer une valeur réelle dans
--               une plage donnée. L'exécution de cette fonction se poursuit jusqu'à ce qu'une
--               valeur valide ait été entrée.
-- Entrées     : invite -> Invite à afficher.
--               min    -> Plus petite valeur acceptée.
--               max    -> Plus grande valeur acceptée.
--               err    -> Message d'erreur à afficher lorsqu'une valeur invalide est entrée.
-- Sorties     : Aucune.
-- Retour      : Valeur réelle entre 'min' et 'max' lue au clavier.
-- Pré         : Aucune.
-- Post        : Aucune.
FUNCTION LireReel(invite : String; min : Float; max : Float; err : String) RETURN Float IS BEGIN
...
END LireReel;

5. Note au sujet des modules externes :

Pour une fonction/procédure qui est dans un module externe (package), le commentaire devrait aller de préférence dans la partie spécification du module (fichier .ADS). Cela est dû au fait que l'utilisateur du module externe (celui qui l'importe dans son programme) n'aura typiquement pas accès à la partie implantation du module. Il est donc bien important qu'il ait toutes les informations nécessaires pour utiliser le module à l'intérieur de la partie spécification (Voir livre de Gabrini chapitre 12 pour de plus amples détails).