Convention générale de codage pour la programmation

Adrien Pellegrini

Bien coder est un art. Apprenons comment y parvenir. ♪

- Titre : Convention générale de codage pour la programmation

- Auteur : Adrien Pellegrini

- Parution : 28 août 2006

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2016 Adrien Pellegrini. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- I-A. Remerciements

- I-B. Préambule

- II. En général

- II-A. Formatage du code

- II-A-1. Indentation

- II-A-2. Accolades

- II-A-3. Interlignes

- II-A-4. Espaces blancs

- II-A-5. Longueur d'une ligne

- II-B. Convention d'écriture

- II-B-1. Langue

- II-B-2. Convention d'écriture des variables

- II-B-3. Convention d'écriture des constantes

- II-B-4. Convention d'écriture des fonctions et des méthodes

- II-B-5. Convention d'écriture des commentaires

- II-B-5-a. Commentaires sur une ligne

- II-B-5-b. Commentaires en fin de ligne

- II-B-5-c. Commentaires multilignes

- II-B-5-d. Documentation du code

- II-B-5-e. À éviter

- III. Langages

- III-A. PHP

- III-A-1. Balises courtes d'ouverture

- III-A-2. TRUE et FALSE

- III-A-3. Imbrication de fonctions

- III-A-4. Concaténation de chaîne

- III-A-5. Les guillemets (quotes)

- III-A-6. mysql_real_escape_string()

- III-A-7. PDO - PHP Data Objects

- III-A-8. addslahes()

- III-B. SQL

- III-B-1. Écriture d'une requête SQL

- III-B-2. Clause WHERE et JOIN

- III-C. HTML et CSS

- III-C-1. Clarté du CSS

- III-C-2. Nom des classes

- III-C-3. Table vs DIV

- IV. Liens

- V. Conclusion

I - Introduction

I-A - Remerciements

Tous mes remerciements à Yogui pour sa relecture.

I-B - Préambule

Ce tutoriel a pour but de vous apprendre les bonnes pratiques pour « bien » coder. Mais sachez qu'il n'y a pas qu'une ni des dizaines de façons de coder.
Sachez aussi que la façon dont vous pouvez coder est assez personnelle, mais il y a des « grands classiques » et des erreurs à éviter.

Un exemple de code « offusqué » qui démontre un style assez particulier avec un code tout à fait correct.

Code offusqué en C

char
_3141592654[3141
],__3141[3141];_314159[31415],_3141[31415];main(){register char*
_3_141,*_3_1415, *_3__1415; register int _314,_31415,__31415,*_31,
_3_14159,__3_1415;*_3141592654=__31415=2,_3141592654[0][_3141592654
-1]=1[__3141]=5;__3_1415=1;do{_3_14159=_314=0,__31415++;for( _31415
=0;_31415<(3,14-4)*__31415;_31415++)_31415[_3141]=_314159[_31415]= -
1;_3141[*_314159=_3_14159]=_314;_3_141=_3141592654+__3_1415;_3_1415=
__3_1415    +__3141;for                 (_31415 = 3141-
__3_1415  ;                  _31415;_31415--
,_3_141 ++,                  _3_1415++){_314
+=_314<<2 ;                  _314<<=1;_314+=
*_3_1415;_31                   =_314159+_314;
if(!(*_31+1)                   )* _31 =_314 /
__31415,_314                   [_3141]=_314 %
__31415 ;* (                   _3__1415=_3_141
)+= *_3_1415                     = *_31;while(*
_3__1415 >=                      31415/3141 ) *
_3__1415+= -                     10,(*--_3__1415
)++;_314=_314                     [_3141]; if ( !
_3_14159 && *                     _3_1415)_3_14159
=1,__3_1415 =                     3141-_31415;}if(
_314+(__31415                      >>1)>=__31415 )
while ( ++ *                       _3_141==3141/314
)*_3_141--=0                        ;}while(_3_14159
) ; { char *                        __3_14= "3.1415";
write((3,1),                        (--*__3_14,__3_14
),(_3_14159                          ++,++_3_14159))+
3.1415926; }                          for ( _31415 = 1;
_31415<3141-                           1;_31415++)write(
31415% 314-(                            3,14),_3141592654[
_31415    ] +                            "0123456789","314"
[ 3]+1)-_314;                            puts((*_3141592654=0
,_3141592654))                              ;_314= *"3.141592";}

II - En général

Cette partie est générale à la programmation dans la plupart des langages. Elle se doit donc être la plus générale possible sans rentrer dans certaines conventions des différents langages.
Pour vous rendre directement à la spécification de certains langages, reportez-vous au Chapitre III.

II-A - Formatage du code

Un code source se présente comme un texte : groupement thématique en paragraphes, indentation pour montrer le niveau d'imbrication, etc. Chaque paragraphe peut être documenté par un commentaire bref.

II-A-1 - Indentation

Une bonne indentation du code permet de mieux s'y retrouver et d'éviter souvent de nombreuses erreurs.
Tous les éditeurs n'interprètent pas les tabulations de la même façon. Certains font qu'une tabulation vaut trois espaces, d'autres cinq espaces. Donc pour faire une indentation, il vaut mieux utiliser les espaces (généralement quatre) plutôt qu'une tabulation.
Comprenez aussi qu'un code écrit comme ci-dessous est quasi illisible !

if ($comment == FALSE)
{
echo 'Error';
}
else
{
echo 'Fine';
}

Un code sous cette forme est bien plus aéré et compréhensible :

if ($comment == FALSE)
{
echo 'Error';
}
else
{
echo 'Fine';
}

Toutefois, veillez à ne pas exagérer avec vos indentations.

II-A-2 - Accolades

Il existe deux façons très utilisées pour placer vos accolades.
Soit vous les placez après le nom de la fonction (comme dans l'exemple ci-dessous), soit vous les placez en dessous.

À côté

function checkpoints($x, $y) {
...
}

En dessous

function checkpoints($x, $y)
{
...
}

Nous vous recommandons la deuxième solution pour des raisons de clarté.
Voici un exemple qui démontre bien que la deuxième solution est la plus adéquate.

if(!empty($_POST)
and !empty($_POST['prenom']) and trim($_POST['prenom']) != ''
and !empty($_POST['nom']) and trim($_POST['nom']) != '')
and !empty($_POST['adresse']) and trim($_POST['adresse']) != '')
{
// traitement du formulaire...
}

Ce qu'il faut éviter
- Les accolades sur la même ligne. Il se peut que votre fonction ne fasse qu'une ligne de code. Dans ce cas, il ne faut pas les écrire toutes sur la même ligne.

à éviter

function checkpoints($x, $y) { return FALSE; }

- Les accolades facultatives.

à éviter

while ($x != $y) $x++;

II-A-3 - Interlignes

Aérer votre code avec des espaces blancs améliore souvent la structure de votre code. Prenons l'exemple de commentaires.

// A variable
$myVar = 0;
// An other variable
$otherVar = 1;

Ce code peut devenir très vite chargé. Préférez ceci :

// A variable
$myVar = 0;

// An other variable
$otherVar = 1;

Ainsi, on voit mieux à quelle ligne de code correspond le commentaire.

II-A-4 - Espaces blancs

Veillez à toujours bien espacer vos variables de vos opérateurs.
Ceci :

$total = $apple + $pear;

est bien plus lisible que cela :

$total=$apple+$pear;

II-A-5 - Longueur d'une ligne

Veillez à ne pas écrire des lignes de code trop longues. Être obligé d'utiliser la barre de défilement pour voir la fin du code n'est vraiment pas une bonne solution.
80 caractères sur une ligne semblent être la limite pour convenir à toutes les résolutions actuelles sans devoir utiliser la barre de défilement.

II-B - Convention d'écriture

Afin que tout le monde puisse comprendre l'intérêt d'une telle variable, fonction à tel endroit du code, il est judicieux de bien choisir son nom. Cela permet une autodocumentation du code assez simpliste. Arrangez-vous toujours pour que quiconque lisant votre code puisse le comprendre simplement en voyant les noms.
Veillez aussi à réfléchir à deux fois avant d'écrire une abréviation.

II-B-1 - Langue

Veillez à ne coder qu'en une seule langue. C'est-à-dire qu'il faut éviter de mélanger français et anglais (par exemple).
Ainsi, je vous recommande d'utiliser l'anglais pour la bonne et simple raison que c'est la langue universelle utilisée par les développeurs. Toutes les fonctions prédéfinies sont écrites en anglais.
Prenons un système de recherche dans un système de fichiers. Nous aurons probablement besoin d'une variable pour déterminer le résultat de la recherche. Naturellement, nous pensons à « trouvé »… Le souci est que ce mot comporte un accent, ce qui ne convient pas. Notre variable booléenne s'appellera donc « trouve ». Maintenant, il risque d'y avoir confusion entre le participe passé et la première personne du singulier de ce verbe conjugué au présent… En regardant le nom de cette variable, s'agit-il de la chaîne à trouver ou bien d'un booléen me permettant de savoir si le résultat a été trouvé ?

Il existe une solution très simple : utiliser une langue ne disposant pas de ces accents que nos langues européennes complexes affectionnent tellement. Il s'agit d'une langue qui a subi de grands changements dont le dernier remonte à l'époque de William Shakespeare, l'un des plus grands contributeurs à l'avènement de l'anglais moderne. En bref : codez en anglais.

II-B-2 - Convention d'écriture des variables

Tout naturellement, pour écrire une variable d'un seul mot, écrivez-la, sans majuscule, sous la forme : variable.

Pour écrire une variable qui contient plusieurs mots, deux écritures sont possibles.
Soit vous écrivez vos variables sous la forme : attachedVars.
Soit vous les écrivez sous cette forme : spaced_vars.

Ce qu'il faut éviter

- Les variables trop longues (3, 4 parties maximum) : longVariableLikeThisIsWrong ou long_variable_like_this_is_wrong.

- Les variables qui sont peu compréhensibles : lVar (au lieu de lenghtVar).

- Les variables quasi semblables : myVar et myVars.

- Mettre une majuscule au début des variables : MyVar.

Personnellement et sûrement certains d'entre vous ont pour habitude de nommer les classes avec le premier caractère en majuscule. Ceci afin de bien distinguer les fonctions des classes.

$template = template($variable);
$template = new Template($variable);

À titre indicatif, il existe un système appelé « Hungarian Notation », inventé par Charles Simonyi. Ce système consiste à écrire son type avant chaque variable.
Par exemple, pour écrire une variable qui contiendra un entier, on peut écrire iVar (i pour integer).

II-B-3 - Convention d'écriture des constantes

Par convention, les constantes s'écrivent entièrement en caractères majuscules : CONSTANT.
Pour écrire une constante de plusieurs mots, on utilise l'underscore : MY_CONSTANT.

II-B-4 - Convention d'écriture des fonctions et des méthodes

Pour différencier vos propres fonctions des fonctions prédéfinies, je vous conseille de les écrire sous cette forme : myFunction() ou functions().
Pour les noms de classes en PHP, on utilise souvent : MyClass ou Class.

II-B-5 - Convention d'écriture des commentaires

Les commentaires permettent d'expliquer au lecteur de votre code le fonctionnement de votre programme. Il peut vous sembler ennuyeux de les écrire, mais ils vous seront d'une précieuse aide si vous devez vous relire après quelques mois ou si quelqu'un essaye de comprendre votre code.
Considérez aussi que la pause de commentaires fait partie du temps développement.
Veillez éviter aussi des commentaires inutiles. Ils ne servent pas de décorations !

II-B-5-a - Commentaires sur une ligne

// My comment
if ($comment == FALSE)
{
echo 'Error';
}

// My other comment
if ($variable)
{
echo 'Bon';
}

II-B-5-b - Commentaires en fin de ligne

$myVar = array();    // Array
$test = 0;           // Test variable

Ce commentaire peut souvent remplacer le commentaire sur une ligne, mais, si votre code est assez complexe et long, et si vous avez besoin de mettre beaucoup de lignes en commentaire, veillez à utiliser le type de commentaire précédent.

II-B-5-c - Commentaires multilignes

/* My comment is too long to be written on a simple line
then I think that I'll write it on multi-line */

// else ...

/*
$variable = 1;
$test = false;

if ($test)
{
$variable = 0;
}
*/
echo $variable;

II-B-5-d - Documentation du code

Nombreux développeurs ne connaissent pas cette pratique pourtant bien utile. Elle consiste à documenter son code de telle façon qu'un programme externe puisse fournir les informations utiles concernant le code rien qu'en examinant les commentaires. Pour cela, les commentaires doivent s'écrire d'une certaine façon, par exemple pour les fonctions :

/**
* Check if points are in the ship
* @param int x the height
* @param int y the width
* @return bool TRUE / FALSE
*/
function checkpoints($x, $y)
{
...
}

Comparatif des générateurs de documentation PHP par Hugo Etievant

II-B-5-e - À éviter

- Placer le code en commentaire de cette façon :

if ($comment == FALSE)
{
echo 'Error'.$myVar/*.' !!!!'*/;
}

III - Langages

III-A - PHP

III-A-1 - Balises courtes d'ouverture

L'utilisation des balises courtes d'ouverture <? ?> est déconseillée.
Si vous utilisez les balises courtes d'ouverture et que la directive short_open_tag est à off sur le server, aucune de vos pages ne pourra être exécutée.
Si les short tags sont désactivés, cela peut donner lieu à une situation cocasse (ou catastrophique, suivant le point de vue) : puisque le code PHP n'est pas interprété, il est envoyé au navigateur Web de l'internaute. Il n'est cependant pas affiché dans la page puisque le tag commence par <, ce que le navigateur comprend comme un début de balise HTML, or une balise HTML inconnue du navigateur est ignorée. Ainsi, tout ce qui se trouve jusqu'au > suivant est caché à l'internaute.

III-A-2 - TRUE et FALSE

Il serait bon d'utiliser TRUE et FALSE à la place de 1 et 0.
Voici un lien intéressant sur la Comparaison de types en PHP.

III-A-3 - Imbrication de fonctions

Veillez à limiter l'imbrication de fonctions à 3. Cela vous permettra de ne pas faire d'erreur stupide en vous trompant de paramètre ou en oubliant une parenthèse fermante.

$randomStr = md5(uniqid(microtime() * 100000, TRUE));

III-A-4 - Concaténation de chaîne

Pour concaténer une chaîne en PHP on utilise le point.
Merci de ne pas utiliser la virgule et d'éviter de mettre un espace après le point. Cela ne fait qu'augmenter la taille de la ligne et ce n'est vraiment pas indispensable pour la bonne compréhension du code.

$variable = 'Bonjour';

$text = $variable.' moi';

III-A-5 - Les guillemets (quotes)

Il est bon de savoir la différence entre les guillemets simples (apostrophes) et les doubles (guillemets anglais).
D'une part, les guillemets simples s'exécutent plus vite que les guillemets doubles (voir tableau).
D'autre part, les guillemets doubles interprètent les variables, ce qui a pour conséquence d'allonger le temps d'exécution.
Voici un tableau reprenant le temps d'exécution du code

echo 'Vive Développez'.$variable.' !!<br />';    et     $variable = '.com';

exécuté 100 fois dans une boucle. Seuls les temps minimum et maximum y sont affichés.

Simple guillemets

Double Guillemets

echo 'Vive Développez'.$variable.' !!<br />';

echo « Vive Développez $variable !!<br /> »;

0.476837158203

0.691413879395

0.715255737305

1.47819519043

III-A-6 - mysql_real_escape_string()

mysql_real_escape_string() protège les caractères spéciaux d'une requête MySQL. Cette fonction permet d'éviter les attaques par injection SQL.

Utiliser mysql_real_escape_string() de la façon suivante est complètement absurde.

$variable = htmlentities(mysql_real_escape_string(intval($variable)));

Tout d'abord, la fonction htmlentities() n'est pas destinée à protéger quelque chose prévu pour être stocké dans une base de données.
Ensuite, la fonction intval() permet d'obtenir une valeur numérique entière, ce qui empêche de manière très effective toute tentative d'injection SQL.
Pour finir, mysql_real_escape_string() ne sert strictement à rien ici puisque l'appel à intval() est suffisant.

III-A-7 - PDO - PHP Data Objects

L'extension PDO (PHP Data Objects) est une interface d'abstraction pour les accès à une base de données. Quel que soit le type de base de données que vous utilisez, le code SQL restera le même.
Pour plus d'informations, reportez vous ici.

III-A-8 - addslahes()

Il est préférable d'utiliser les fonctions comme mysql_real_escape_string() (MySQL) ou sqlite_escape_string (SQLite) à la place de addslahes() pour préparer une requête SQL

III-B - SQL

III-B-1 - Écriture d'une requête SQL

Il est préférable de mettre les mots-clés SQL en majuscules pour bien les distinguer de ce qui est défini par l'utilisateur.

select id, nom from etudiant where id < 30;

SELECT id, nom FROM etudiant WHERE id < 30;

III-B-2 - Clause WHERE et JOIN

Vous aurez parfois besoin de sélectionner des données contenues dans plusieurs tables. Pour cela, il est préférable d'utiliser les jointures que la clause WHERE.
Pour anecdote, la prochaine version de SQL Server (qui en est actuellement à la version 2005) interdira les jointures à l'aide du mot clef WHERE.
Voici un lien explicatif sur les jointures par SQLpro

III-C - HTML et CSS

III-C-1 - Clarté du CSS

Au lieu d'écrire quelque chose du genre, il serait bon d'utiliser les feuilles de style !

<DIV style='overflow: auto; height: 250; width: 179; scrollbar-face-color:
#EAEDF4; scrollbar-highlight-color: #EAEDF4; scrollbar-shadow-color: #EAEDF4;
scrollbar-3dlight-color: #EAEDF4; scrollbar-arrow-color: #5F107C;
scrollbar-track-color: #EAEDF4; scrollbar-darkshadow-color: #EAEDF4'>
<p style="margin-top: 0; margin-bottom: 0">
<font color="#6801F5" face="Verdana" size="1">

III-C-2 - Nom des classes

Il ne faut pas nommer une classe en fonction de l'apparence qu'elle donne à l'élément.
Si l'on prend l'exemple d'une classe nommée « yellow-box », qui comme son nom l'indique, mettrait une couleur de fond jaune à la boite. Plus tard, si vous voulez changer la couleur de fond, non seulement il faudra modifier le code CSS de la classe, mais en plus modifier son nom. Ça n'aurait plus aucun sens de la nommer « yellow-box » si la couleur de fond est orange.

Normalement, toute classe CSS est destinée à être appliquée à un type particulier d'élément visuel selon ce qu'il contient, par exemple une réponse dans le forum (la case complète avec la partie pseudo + le titre + le contenu) de classe « forum-answer » ou simplement le message de cette réponse « forum-answer-message ». Tout est dans la sémantique.
Au-delà des problèmes évidents de maintenance, il est tout à fait probable que les moteurs de recherche, lors de leurs opérations de référencement, examinent ces classes CSS de manière à donner de bons ou de mauvais points selon leur utilisation.

III-C-3 - Table vs DIV

Les tableaux servent à afficher des données tabulaires et non à structurer une page.
Pour structurer une page, vous devez utiliser la balise div et pour le style, CSS.

IV - Liens

- CSS : Notions de base

- Bonnes pratiques de SEO ('white hat techniques')

- Div et CSS : une mise en page rapide et facile

- Apostrophes ou guillemets : lesquels choisir ?

- Standards de codage du projet PHP::PEAR

- Google : « coding practices »

V - Conclusion

Adopter une façon de coder « standard » permet à tout le monde de se comprendre en lisant le même code. Il n'est pas nécessaire de la respecter à la lettre, mais du moins ce qui est énoncé ici paraît le strict minimum à savoir.
De plus, coder d'une façon ou d'un autre n'a aucun effet sur le comportement du code, mais le faire proprement n'aura que des avantages.