I. Règles de programmation▲
I-A. Règle de nommage▲
I-A-1. Les fichiers sources▲
Le nom d'un fichier source doit être significatif du contenu.
I-A-2. Les noms des variables▲
I-A-2-a. Les variables locales▲
Le nom d'une variable doit définir son contenu.
La première lettre doit être en majuscule et les autres en minuscule.
Tous les mots composants une variable sont séparés par "_".
Exemple : Nom_voiture, Nom_magasin, Nb_contraintes, ...
I-A-2-b. Les variables globales▲
Il est interdit d'avoir des variables globales.
I-A-2-c. Les noms de variables interdites▲
Les variables nommées 'temp', 'prov', ... sont à proscrire ainsi que les variables proches des mots clés comme 'For', 'Socket', 'New'
I-A-3. Les noms des constantes▲
Le nom d'une constante doit définir son contenu.
Toutes les lettres sont en MAJUSCULE.
Tous les mots composants une constante sont séparés par "_".
Exemple : TAILLE_MAXI, ...
I-A-4. Les macro-commandes▲
Le nom d'une macro -commande est en MAJUSCULE.
Tous les mots composants une macro-commande sont séparés par "_".
Elles permettent de simplifier une séquence de traitement.
Exemples :
EST_NUMERIQUE(a) (("0"<=a)&&(a<="9"))
EST_CORRECTE(Valeur) (Valeur!=(t_Valeur *)NULL)
EXISTE(Valeur) (Valeur!=(t_Valeur *)NULL)
I-A-5. Les noms d'une fonction et d'une procédure▲
I-A-5-a. Une action▲
Le nom d'une fonction ou d'une procédure correspondant à une action doit
commencer par un verbe à l'infinitif.
La première lettre est en majuscule.
Toutes les autres lettres sont en minuscule.
Tous les mots composants le nom d'une fonction ou d'une procédure sont séparés par
"_".
Exemple : Traiter_demande()
I-A-5-b. Une vérification▲
Le nom d'une fonction ou d'une procédure correspondant à une action doit
commencer par un verbe conjugué au présent.
La première lettre est en majuscule.
Toutes les autres lettres sont en minuscule.
Tous les mots composants le nom d'une fonction ou d'une procédure sont séparés par
"_".
Exemple : Est_entier()
I-A-5-c. Les noms des paramètres▲
Les noms des paramètres respectent la règle des noms de variables décrit ci-dessus.
Ils sont cependant préfixés par :
- "i_" pour un paramètre d'entrées
- "o_" pour un paramètre de sorties
- "io_" pour un paramètre d'entrée -sortie
Exemple : i_Indice, io_Information, o_Resultat, ...
I-A-5-d. Les procédures et les fonctions sans aucun paramètre▲
Ces procédures et ces fonctions doivent être suffixées par (void).
Exemple : void Ma_procedure(void);
I-A-6. Les index de boucles▲
Nous autorisons l'utilisation des variables i, j et k pour les index de boucles.
I-A-7. Les noms des types▲
I-A-7-a. Les types structurés▲
Les noms des types structurés respectent la règle des noms de variables décrit ci-dessus.
Ils sont préfixés par "t_".
Exemple : t_Vehicule
I-A-7-b. Les types énumérés▲
Les noms des types énumérés respectent la règle des noms de variables décrit ci-
dessus. Ils sont préfixés par "e_".
Les valeurs du type énuméré sont écrites comme les constantes.
Il faut utiliser ces types aussi souvent que possible.
Exemple : enum { ROUGE, VERT, BLEU } e_Couleur
I-A-7-c. Les types unions▲
Les types unions ne doivent pas être utilisés, cela nuit à la lisibilité du code.
I-A-8. Les abréviations▲
Elles sont tolérées dans la limite des abréviations communes.
Exemple : Nb : Nombre , Cpt : Compteur, Maxi : Maximum, Ref : Reference, Mini : Minimum...
I-B. Présentation du code▲
I-B-1. Règles générales▲
Les différentes parties d'une fonction ou d'une procédure sont indiquées par des
commentaires explicatifs accompagnés éventuellement d'un algorithme permettant de préciser
le fonctionnement.
Les conditions ou les itérations sont décrites dans un commentaire la précédant sauf si
le code est suffisamment explicite.
L'indentation doit être d'une tabulation (correspondant à 2 espaces).
Les accolades ouvrantes et fermantes respectives doivent être positionnées à la même
colonne (l'une en dessous de l'autre sur la même colonne).
Il faut caster les objets ayant des types différents pour les comparer ou les affecter (ex:
comparaison d'un entier avec un réel, affectation du résultat d'une allocation ou comparaison
d'un pointeur avec NULL).
Ne pas effectuer d'affectations dans une condition.
Ne pas utiliser les instructions 'break'(sauf dans un switch) et 'continue'.
I-B-2. Description d'un header▲
I-B-2-a. Un entête▲
L'entête d'un header est une zone de commentaire permettant de décrire brièvement le
contenu du module ainsi que les différentes évolutions subies par le module, par qui et quand.
Exemple :
/* ------------------------------------------------------------------------- */
/* Gestion de la classe t_Information */
/* ------------------------------------------------------------------------- */
/* OBJET : Structure de donnees dynamiques permettant de gerer un ensemble */
/* d'informations (Cle, Valeur) */
/* ------------------------------------------------------------------------- */
/* DATE | AUTEUR | COMMENTAIRES */
/* ------------------------------------------------------------------------- */
/* 08/11/1999 | A.L | Creation des fichiers */
/* 01/12/1999 | A.L | Creation de la classe t_Information */
/* 04/01/2000 | A.L | Mise a disposition des outils */
/* 17/03/2000 | E.P | Methodes de lecture ensemble infos */
/* 09/08/2001 | A.L | Extraction, Ajout, Suppression d'une partie */
/* ------------------------------------------------------------------------- */
/* CARACTERISTIQUE TECHNIQUE DU MODULE : */
/* */
/* LIMITES : Une ligne dans un fichier texte a lire ou a ecrire ne peut */
/* exceder 512 octets (ATTENTION : Effet de bord possible) */
/* ------------------------------------------------------------------------- */I-B-2-b. L'encadrement▲
Le header est encadré par une directive qui teste si une macro est déjà définie ou pas.
Cet encadrement a pour rôle de ne pas avoir de multiples inclusions d'un header.
Exemple :
#IFNDEF _al_<nom fichier>_h
#DEFINE _al_<nom fichier>_h
/* ...
contenu du header
... */
#ENDIFI-B-2-c. Les inclusions▲
Cette zone contient l'ensemble des inclusions nécessaires aux fonctionnements du
module.
Exemple :
#include <stdio.h>
#include <stdlib.h>I-B-2-d. Les constantes▲
Les constantes nécessaires aux types sont définies par DEFINE dans cette partie.
Exemple :
#define TAILLE_MAXI 10I-B-2-e. Les types▲
Cette zone contient la description de tous les types utilisables.
Exemple :
typedef struct t_Pays
{
char Nom[TAILLE_MAXI+1];
long Nb_habitants;
} t_Pays;I-B-2-f. Les fonctions et les procédures utilisables▲
Le header contient les prototypes des différentes fonctions et procédures d'accès au
module. Ce sont les outils manipulés par les autres modules. Le header ne contient que les prototypes d'accès au module. La description de Son utilisation, la liste des paramètres en entrées et/ou en sortie ainsi que le résultat du traitement doivent figurer dans le fichier source
C.
Il faut précéder le prototype de la fonction par la classe "extern".
Exemple :
extern int Est_entier(char *i_Chaine);I-B-2-g. Exemple de header▲
/* ------------------------------------------------------------------------- */
/* Gestion de la classe t_Information */
/* ------------------------------------------------------------------------- */
/* OBJET : Structure de donnees dynamiques permettant de gerer un ensemble */
/* d'informations (Cle, Valeur) */
/* ------------------------------------------------------------------------- */
/* DATE | AUTEUR | COMMENTAIRES */
/* ------------------------------------------------------------------------- */
/* 09/08/2001 | A.L | Extraction, Ajout, Suppression d'une partie */
/* ------------------------------------------------------------------------- */
/* CARACTERISTIQUE TECHNIQUE DU MODULE : */
/* */
/* LIMITES : Une ligne dans un fichier texte a lire ou a ecrire ne peut */
/* exceder 512 octets (ATTENTION : Effet de bord possible) */
/* ------------------------------------------------------------------------- */
#include <stdio.h>
#include <stdlib.h>
#include "al_journal.h"
/* --------------------------------- */
/* definition des messages d'erreurs */
/* --------------------------------- */
#define INF0001 "INF0001: Erreur d'allocation memoire"
/* ... */
/*--- DEFINITION DES CONSTANTES ---*/
#DEFINE LONGUEUR_IDENTIFIANT 10
/*--- DEFINITION DES MACROS COMMANDES ---*/
#DEFINE EST_NUMERIQUE(a) (('0'<=a)&&(a<='9'))
/*--- DEFINITION DES STRUCTURES ---*/
typedef struct t_Information
{
char Identifiant[LONGUEUR_IDENTIFIANT+1];
int Valeur;
} t_Information;
typedef t_Liste_generique t_Liste_information;
/*--- DEFINITION DES PROTOTYPES UTILISABLES ---*/
extern int Est_message(char *i_Chaine);
#ENDIFI-B-3. Description d'un fichier source C▲
I-B-3-a. L'entête du corps▲
L'entête d'un corps est une zone de commentaire permettant de décrire brièvement le contenu du module et les remarques techniques ainsi que les différentes évolutions subies par
le module, par qui et quand.
Exemple :
/* ------------------------------------------------------------------------- */
/* Gestion de la classe t_Information */
/* ------------------------------------------------------------------------- */
/* OBJET : Structure de donnees dynamiques permettant de gerer un ensemble */
/* d'informations (Cle, Valeur) */
/* ------------------------------------------------------------------------- */
/* DATE | AUTEUR | COMMENTAIRES */
/* ------------------------------------------------------------------------- */
/* 08/11/1999 | A.L | Creation des fichiers */
/* 01/12/1999 | A.L | Definition des methodes et de la classe */
/* | | t_Info */
/* 01/12/1999 | A.L | Creation de la classe t_Information */
/* 04/01/2000 | A.L | Mise a disposition des outils */
/* 23/03/2000 | A.L | Remplacement de la classe t_Info par une */
/* | | structure simplifiee */
/* 09/08/2001 | A.L | Extraction, Ajout, Suppression d'une partie */
/* ------------------------------------------------------------------------- */I-B-3-b. L'inclusion▲
Le module doit inclure le header qui le caractérise.
Exemple :
#include "al_outils.h"I-B-3-c. Description des types internes au module▲
Les types communs sont décrit dans le header.
Les types propres au fichier source C sont décrits ici. Ces types ne seront exploitables
que par le fichier source.
I-B-3-d. Les fonctions et les procédures internes au module (non accessible par d'autres modules)▲
Cette partie comprend le codage des fonctions et des procédures propres au module.
Elle doit comprendre un entête (description des fonctionnalités) qui précise la portée de la
fonction ou procédure et un corps (codage C).
Les prototypes doivent être précédés de la classe 'static'.
Exemple :
/* -------------------------------------------------------------------- */
/* DESCRIPTION : Permet de déterminer si la chaine est un entier ou pas */
/* -------------------------------------------------------------------- */
/* ENTREES : Chaine : chaine de caractères à analyser */
/* -------------------------------------------------------------------- */
/* SORTIES : Valeur : conversion de la Chaine */
/* -------------------------------------------------------------------- */
/* RETOUR : 0 : Chaine n'est pas un entier, Valeur n'est pas modifiée */
/* 1 : Chaine est un entier, Valeur contient la conversion */
/* -------------------------------------------------------------------- */
static int Est_entier(char *i_Chaine,int *o_Valeur)
{
/* ... */
}I-B-3-e. Les fonctions et les procédures d'accès au module▲
Cette partie comprend le codage des fonctions et des procédures dont les prototypes
sont décris dans le header. Les prototypes ne sont précédés d'aucune classe d'appartenance.
Exemple :
/* -------------------------------------------------------------------- */
/* DESCRIPTION : Permet de déterminer si la chaine est un message */
/* -------------------------------------------------------------------- */
/* ENTREES : Chaine : chaine de caractères à analyser */
/* -------------------------------------------------------------------- */
/* RETOUR : 0 : Chaine n'est pas un message */
/* 1 : Chaine est un message */
/* -------------------------------------------------------------------- */
int Est_message(char *i_Chaine)
{
/* ... */
}I-B-4. Déclarations des variables▲
Une variable doit être initialisée dés sa déclaration. Si elle doit prendre des valeurs
particulières pour indiquer un sens, ces valeurs doivent être décrites dans un commentaire à
côté. Dans ce cas, si le nombre de valeurs pouvant être prises sont dénombrables, il est
préférable d'utiliser un type énuméré.
Exemple :
int i = 0 ;
t_Vehicule Vehicule = (t_Vehicule *)NULL;/* NULL: pas de véhicules */
t_Individu *Individu=Instancier_individu("LESERT Aymeric") ;I-B-5. Les fonctions et les procédures▲
I-B-5-a. Ordre d'écriture ou de déclaration des fonctions et des procédures▲
Il faut TOUJOURS spécifier la fonction avant de l'utiliser.
REMARQUE : Dans le cas de récursivité croisée, il faudra déclarer le prototype de la
fonction appelée avant la fonction appelante.
I-B-5-b. Les fonctions et les procédures utilisables▲
Elles comportent 4 parties :
- Déclaration et initialisation des variables
- Vérifie la cohérence des données (programmation défensive)
- Traite les données
- Retourne les résultats
La partie 3 ne doit pas effectuer de « return ».
Exemple :
/* -------------------------------------------------------------------- */
/* DESCRIPTION : Permet de déterminer si la chaine est un message */
/* -------------------------------------------------------------------- */
/* ENTREES : Chaine : chaine de caractères à analyser */
/* -------------------------------------------------------------------- */
/* RETOUR : 0 : Chaine n'est pas un message */
/* 1 : Chaine est un message */
/* -------------------------------------------------------------------- */
int Est_message(char *i_Chaine)
{
/* déclaration et initialisation des variables */
int Longueur = 0 ;
int Nb_informations = 0 ;
/* contrôle de la cohérence des données */
Longueur = strlen(i_Chaine) ;
if ((0>Longueur)||(Longueur>200))
return(-1);
/* traitement */
/* ... */
/* retour */
return (Nb_informations) ;
}I-B-5-c. Les fonctions et les procédures internes au fichier source▲
Elles comportent 3 ou 4 parties :
- Déclaration et initialisation des variables
- Vérifie la cohérence des données (programmation défensive)
- Traite les données
- Retourne les résultats
La partie 3 ne doit pas effectuer de « return ».
I-C. Exploitation de la présentation du code▲
Grâce à la normalisation décrite ci-dessus, il est concevable de mettre en place un outils permettant de réaliser une documentation on-line (au format HTML afin de les consulter avec un browser).