L'art du codage
--------------- Par S/ash (sl4sh@ifrance.com)

Ceci n'est pas un article sur la programmation en elle-mme mais plutt sur la
faon de prsenter un fichier source. J'expliquerai ici dans le cas du langage
C/C++ mais cela est extensible  tous les autres langages.

I. L'indentation
Votre code source doit avoir une identation cohrente (faon de disposer les
espaces et les autres symboles dans un code source) et surtout elle doit tre
homogne dans tous les fichiers sources d'un mme programme (pour ma part
j'utilise celle par dfaut d'Emacs).

II. Les fonctions
Les fonctions ne doivent pas tre trop grosses (une rgle appliqu dans
certains tablissements est de ne pas dpasser 25 ou 30 lignes de code par 
fonctions). Chaque fonction doit avoir pour but une seule action : on ne doit
pas runir par exemple, une fonction d'ouverture d'un fichier avec une autre 
d'enregistrement.

III. Le nommage des variables et fonctions
Chaque fonction ou variable doit avoir un nom clair et prcis. Ce nom ne doit
cependant pas tre trop long (C'est chiant  taper 20 caractres).
Par exemple, un index de boucles ou de tableau va tre nomm i ou j ou k...
Un autre exemple est si j'ai une fonction qui va classer une liste de fichier
par date, il ne faut pas la nommer fonction_qui_classe_par_date mais plutt
classe_date (moi je l'appelerai personnellement datesort).
De mme, il faut que vous ayez une facon de nommer cohrente dans un code
source (par exmple je nomme pour des fonctions classiques en C en miniscule
avec des underscores (_) si ncessaire et les fonctions destine  tre 
rutilise avec des majuscules au dbut des mots (CommeCeci)).
Dans certains cas on peu ngliger le nommage comme lors de variables 
temporaires ou de fonction ne servant qu' un endroit (utilise par exemple
dans une fonction de tri). Il est galement inutile de se tracasser sur les 
arguments des fonctions triviales (d'initialisation en particulier).
Le mieux est encore d'adopter une convention clairement expliqu dans un
fichier join  vos source. Le top en matire de convention de nommage est
lorsque, par exemple, on dit que tout les noms seront du type ab_Nom ou a est
une lettre ou une  srie de lettre dsignant le type de variables (p pour 
pointeur ou pi pour pointeur sur entier) et b la porte de la variables (g
pour globales, l pour locales...) et enfin Nom est un nom explicite (ce type
de nommage est rapidement chiant pour le codeur mais trs pratiques pour le
relecteur). Une de ces conventions est celle prise par Micro$oft pour les
fonctions de l'API windows nomme notation Hongroise.

IV. L'organisation des modules
Les modules (en gnrales les diffrents fichiers sources) doivent chacun
avoir une fonction prcisent sans aller empietiner sur les autres...
On ne doit pas crire dans un mme modules par exemple, les fonctions
algorithmiques et les fonctions d'interfaces.

V. Les commentaires
Les codes sources doivent tre pleinement accompagn de commentaire.
Tout d'abord chaque fichier doit contenir un en-tte expliquant  quoi sert le
fichier. Ensuite chaque fonction doit tre comment par un petit texte
clair. Pour ma part je mets galement lors des fonctions non triviales la
liste des entres et sorties de la fonction.
Chaque bouts de code doit tre expliqu pour dire ce qu'il fait et, si on a le
courage, comment on le fait.
Enfin, les lignes qui sembles compliqu ou les algorithmes un peu ardu doivent
tre expliqu dans leur mthode (ca je ne le fais pas tous le temps).

VI. A quoi ca sert tout a ?
Ben, dans la plupart des cas, un code source est fait pour tre diffus (c'est
ma philosophie) ou du moins rvis et corrig. Ceci facilitera la chasse aux
bugs, la comprhension des autres sur le code et vos futures relectures...

Un petit dernier mot...
L'art du codage est surtout une histoire de bon sens, il s'agit simplement de
rendre un code clair et non de retrouver lecharabia que l'on peut voir dans
certaines sources comme celle de certains auteurs de la GNU ou de chez M$...
L'art du codage est une route longue et difficile. En effet, crire un code
source clair et comprhensible n'est pas une chose aise.
Pour ma part, le summum dans ce domaine est une technique que j'ai vu dans une
bote ayant t class premier europen en qualit logicielle.

<--                          File by S/ash                                 -->
[EOF]
