Aller au menu - Aller au contenu

Icône Codez proprement

Par Avatar Mathieu Nebra (M@teo21)
Mise à jour : 03/04/2010
Difficulté : Facile Facile Creative Commons BY-NC-SA
159 191 visites depuis 7 jours , dont 460 sur ce chapitre , classé 3/777
En programmation comme partout ailleurs, il y a 2 types de personnes :
  • Ceux qui effectuent leur travail rapidement, mais ne se soucient pas de la qualité, de la lisibilité, et de l'évolutivité de leur code.
  • Ceux qui font l'effort de soigner un peu leur travail, car ils ont conscience que ce petit travail supplémentaire sera un gain de temps énorme à l'avenir.
Il va de soi que le 2ème type de personne est de loin le meilleur. ^^
Toutefois, quand on débute, on a tendance à se dire "Ca marche, parfait, ne touchons plus à rien et laissons comme ça". C'est un mauvais réflexe, et je ne serai pas le seul à vous le dire : n'importe quel programmeur PHP ayant un peu d'expérience sait qu'un code qui marche n'est pas forcément bon.

Cette annexe est en fait une suite de petits conseils apparemment peu importants, sur lesquels je voudrais que vous portiez toute votre attention.
C'est peu de choses, et c'est pourtant ce qui fait la distinction entre un "bon" programmeur et euh... un programmeur du Dimanche ! :p
Retour en haut
Sommaire du chapitre :
Icône du chapitre
Chapitre précédent Sommaire Chapitre suivant
Retour en haut

Des noms clairs

J'ai pas mal insisté dessus dans les premiers TP du tutoriel PHP, et cette fois j'y reviens avec un peu plus d'explications.
Quand vous créez un script PHP, vous devez inventer des noms. Vous allez devoir donner des noms à différents types d'éléments :
  • Les variables
  • Les fonctions
  • Les classes
L'idée est simple : il faut que vous fassiez l'effort de choisir des noms de variables et de fonctions clairs et compréhensibles.
Par exemple, voici des mauvais noms de variables :
  • $temp
  • $skrkds
  • $x
  • $data
  • $info
  • $val
  • $val2

Je n'ai pas inventé ces noms de variables, en fait pour tout vous dire ce sont des noms que j'ai vraiment vus dans de nombreux codes source.

Par exemple, $info : "info", oui mais info sur QUOI ?
C'est pourtant ça qui est crucial : savoir ce que contient une variable. Une variable contient toujours une info, c'est à vous de préciser laquelle.
Je ne vous parle même pas des variables "sans nom" : $temp, $tmp et compagnie. Ces noms sont à bannir absolument.

Mais à quoi ça peut servir de chercher un nom de variable clair ? Après tout, c'est mon code, c'est pour moi, je comprends très bien ce que je fais !

Faux.
Bien sûr que vous savez ce que vous faites (personne n'est dans votre esprit après tout :p ). Et pourtant le problème peut apparaître dans 2 cas :
  • Si vous donnez votre code PHP à un ami pour qu'il vous aide à un endroit où vous bloquez, ou pour qu'il continue votre code. Essayez par exemple de montrer votre code PHP sur des forums sur internet, vous verrez que si vous utilisez des noms peu clairs, vous aurez beaucoup moins de réponses parce qu'il aura été bien plus difficile de comprendre le fonctionnement de votre code !
  • Un autre cas (sous-estimé), c'est celui où vous retouchez votre code plus tard. Je ne dis pas le lendemain (les idées sont encore fraîches), mais dans 3 mois, ou même dans 3 semaines. Croyez-en mon expérience : il m'est arrivé de devoir relire mon code source en me demandant "Mais qu'est-ce que j'ai bien pu vouloir faire là ?"
Passez ne serait-ce qu'une seconde de plus à réfléchir à des noms clairs. N'ayez pas peur de mettre des noms un peu longs, ce n'est pas une perte de temps, bien au contraire.

Vous pouvez utiliser le symbole underscore "_" pour remplacer les espaces, qui sont je vous le rappelle, interdits dans les noms de variables et de fonctions.

Voici quelques exemples de noms de variables clairs :
  • $ip_visiteur
  • $pseudo_membre
  • $date_news
  • $mot_de_passe
  • $forum_selectionne
Pour finir, et en espérant vous convaincre parce que croyez-moi c'est très important, voici le même code source en deux exemplaires :
  • Le premier contient des noms courts et pas clairs, il est difficile de comprendre rapidement ce qu'il fait.
  • Le deuxième contient des noms un peu plus longs, mais au moins on arrive de suite à savoir à quoi sert telle variable et telle fonction.
Ces 2 codes produisent exactement le même résultat, simplement l'un d'entre eux est beaucoup plus compréhensible que l'autre.
Je vous laisse deviner lequel ;)

Des noms de variables peu clairs



Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
<?php
$mess_page = 20;

$ret = $bdd->query('SELECT COUNT(*) AS nb FROM livre');

$data = $ret->fetch();
$total = $data['nb'];
 
$nb_total  = ceil($total / $mess_page);
 
echo 'Page : ';
for ($i = 1 ; $i <= $nb_total ; $i++)
{
    echo '<a href="livre.php?page=' . $i . '">' . $i . '</a> ';
}
 
?>


Des noms de variables beaucoup plus clairs



Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?php
$nombreDeMessagesParPage = 20;
 
$retour = $bdd->query('SELECT COUNT(*) AS nb_messages FROM livre');
$donnees = $retour->fetch();
$totalDesMessages = $donnees['nb_messages'];
 
$nombreDePages  = ceil($totalDesMessages / $nombreDeMessagesParPage);
 
echo 'Page : ';
for ($page_actuelle = 1 ; $page_actuelle <= $nombreDePages ; $page_actuelle++)
{
    echo '<a href="livre.php?page=' . $page_actuelle . '">' . $page_actuelle . '</a> ';
}
?>

C'est fou comment des noms écrits correctement en français permettent d'y voir plus clair. :)
Retour en haut

Indentez votre code

Une des premières choses qui saute aux yeux quand on regarde un code source, c'est son indentation.

Le principe de l'indentation, c'est d'utiliser intelligemment les tabulations pour "décaler" certaines parties de votre code, afin de montrer plus clairement la structure.
La quasi-totalité des éditeurs de texte ont l'habitude que vous utilisiez du code indenté, et vous aident donc beaucoup à clarifier votre code.

Quand je dis "la plupart", je ne parle pas de Bloc-notes. Si vous tapez votre code PHP sous bloc-notes, vous feriez bien d'essayer un vrai logiciel fait pour ça, comme Notepad++ dont je vous ai parlé dans le deuxième chapitre.
Non seulement avec un vrai éditeur vous avez une indentation du code semi-automatique, mais en plus votre code est coloré tout seul, ce qui aide énormément croyez-moi !

Il y a plusieurs "styles" d'indentation de code, cela varie un peu selon les goûts des développeurs. Celui que je vous propose est simple à retenir :
  • A chaque fois que vous ouvrez des accolades {, par exemple pour if, un while ou un for, vous décalez tout le code qui suit d'une tabulation vers la droite.
  • A chaque fois que vous fermez une accolade }, vous décalez tout le code qui suit d'une tabulation vers la gauche.

Avec un code non indenté


C'est plus clair avec un exemple, alors voyez-vous même. Voici ce que ça donne avec un code non indenté :

Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php
for ($ligne = 1 ; $ligne <= 100 ; $ligne++)
{
if ($ligne % 2 == 0)
{
echo $ligne . ' : <strong>ligne paire</strong>';
}
else
{
echo $ligne . ' : <em>ligne impaire</em>';
}
echo '<br />';
}
?>

Avec un code indenté


Et voici maintenant le même code correctement indenté si on respecte la règle des tabulations :

Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?php
for ($ligne = 1 ; $ligne <= 100 ; $ligne++)
{
    if ($ligne % 2 == 0)
    {
        echo $ligne . ' : <strong>ligne paire</strong>';
    }
    else
    {
        echo $ligne . ' : <em>ligne impaire</em>';
    }
    
    echo '<br />';
}
?>

L'avantage avec un code indenté, c'est qu'on voit bien les "niveaux" des instructions. On sépare bien les blocs, et on arrive à se repérer bien plus facilement. :)
Avoir un code correctement indenté, c'est quasiment indispensable lorsque vous commencez à faire des scripts de plusieurs dizaines de lignes (ce qui arrive assez vite !).

Certains développeurs ont tendance à remplacer les tabulations par 2 ou 4 espaces, car la largeur d'une tabulation peut varier d'un logiciel à un autre, alors que celle d'un espace est fixe. En général, c'est l'éditeur de texte lui-même qui convertit nos tabulations par des espaces, de façon transparente.

Retour en haut

Un code correctement commenté

Le dernier point, peut-être le plus délicat pour des raisons de dosage, concerne les commentaires dans le code.
Les commentaires ne servent à rien, puisqu'ils ne sont pas lus par PHP lors de la génération de la page... Comme les noms de variables et l'indentation du code me direz-vous.

En effet, là encore les commentaires sont pour vous, et éventuellement pour la personne qui lira votre code. Il faut commenter votre code, mais il ne faut surtout pas tomber dans l'excès !

Je m'explique. Si après une ligne comme celle-ci :

Code : PHP
1
<?php echo $pseudo_visiteur; ?>


... vous rajoutez le commentaire "Affiche le pseudo du visiteur", là je dis non, non et non !

Il est strictement inutile de commenter chaque ligne de votre code une à une ! Si j'ai insisté tout à l'heure pour que vous mettiez des noms de variables et de fonctions clairs, c'est justement pour vous éviter à avoir besoin de trop commenter.

Le plus judicieux et le plus intelligent, c'est de commenter un "groupe de lignes", pour expliquer brièvement à quoi elles servent quand cela n'est pas évident.
C'est le sens général de votre code que vous devez expliquer dans les commentaires, et non pas le rôle de chaque ligne !

Pour vous aider, il existe 2 types de commentaires :
  • Ceux qui commencent par // : ils permettent de commenter sur une seule ligne à la fois.
  • Ceux qui commencent par /* et qui se terminent par */ : ils sont utilisés pour des longs commentaires s'étalant sur plusieurs lignes.
Voici une petite illustration d'un code correctement commenté :

Code : PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<?php
/*
Script "Questionnaire de satisfaction"
    Par M@teo21
    
Dernière modification : 20 Août XXXX
*/

// On vérifie d'abord s'il n'y a pas de champ vide
if ($_POST['description'] == NULL OR $_POST['mail'] == NULL)
{
    echo 'Tous les champs ne sont pas remplis !';
}
else // Si c'est bon, on enregistre les informations dans la base
{
    $bdd->prepare('INSERT INTO enquete VALUES (\'\', ?, ?)');
    $bdd->execute(array($_POST['description'], $_POST['mail']));    
    
    // Puis on envoie les photos
    
    for ($numero = 1 ; $numero <= 3 ; $numero++)
    {
        if ($_FILES['photo' . $numero]['error'] == 0)
        {
            if ($_FILES['photo' . $numero]['size'] < 500000)
            {
                move_uploaded_file($_FILES['photo' . $numero]['tmp_name'], $numero . '.jpg');
            }
            else
            {
                echo 'La photo ' . $numero . 'n\'est pas valide.<br />';
                $probleme = true;
            }
        }
    }
    
    // Enfin, affichage d'un message de confirmation si tout s'est bien passé
    
    if (!(isset($probleme)))
    {
        echo 'Merci ! Les informations ont été correctement enregistrées !';
    }
}
?>

Comme vous le voyez, je n'ai pas commenté toutes les lignes. J'ai juste commenté des groupes de lignes pour expliquer leur fonction globale, ce qui me permettra à moi (ou à un autre) de se repérer beaucoup plus facilement dans le code plus tard !
Retour en haut
Ces petits conseils n'ont l'air de rien comme ça, mais ils valent de l'or. ^^

Alors certes, je ne vous cache pas que chaque programmeur a ses petites habitudes et la façon de faire n'est pas partout la même. Pourtant, ces conseils constitueront pour vous un bon point de départ pour que vous preniez les bonnes habitudes.

En faisant l'effort de les respecter, vous gagnerez beaucoup plus que ce que vous ne le pensez. Et vous verrez que, le jour où vous devrez débugger un gros code qui a décidé de ne plus marcher, vous serez vraiment heureux d'avoir indenté, commenté et utilisé des noms clairs dans votre code. :D
Chapitre précédent Sommaire Chapitre suivant
Retour en haut

Partager

Retour en haut
19 commentaires pour "Codez proprement"
Note moyenne : 3.61 / 4 (2420 votes)
Pseudo Commentaire
Hors ligne Woldred # Posté le 27/12/2009 à 01:22:02
Avatar

 Bonjour,
il y a une petite erreur dans la partie Un code correctement commenté, à la ligne 16 du code source PHP. Vous avez oublié d'échapper les apostrophes à l'intérieur de la requête SQL.

Votre code source :
Code : PHP
1
2
3
<?php
    mysql_query('INSERT INTO enquete VALUES ('', '' . nl2br(htmlentities($_POST['description'])) . '', '' . htmlentities($_POST['mail']) . '')');
?>



Le code source corrigé :

Code : PHP
1
2
3
<?php
    mysql_query('INSERT INTO enquete VALUES (NULL, \'' . nl2br(htmlentities($_POST['description'])) . '\', \'' . htmlentities($_POST['mail']) . '\')');
?>


Bonne continuation ! :D
Hors ligne Mikilo # Posté le 14/01/2010 à 00:25:17
Lintury Under Construction...
Avatar

 Là il y certains points où je suis pas vraiment en accord.

Quand on nomme une variable $pass, pour moi ça revient strictement au même que de l'appelé $mot_de_passe. Les variables comme $tmp ou $data je les trouves utile.
Par exemple dans les autres tutos, Mateo a pour habitude de nommer $donnees les requêtes SQL, on remarquera que donnees et data, ça revient un peu au même. C'est juste la traduction anglaise.

Je ne mets pas de note, mais je dirai qu'il y a encore pas mal de choses à voir. Je ne dis pas que le tuto est bidon, mais que ça ne reflète pas vraiment la réalité. Il y a des conventions que les programmeurs respectent et aussi des "abus" qui seront un jour ou l'autre utilisés.
Pour finir, il ne faut pas les bannir ces termes. Mais les utiliser judicieusement.
-=[Mikilo]=-
 
Hors ligne RyDroid # Posté le 23/09/2010 à 22:04:19
rayquaza devient RyDroid
Avatar

Avis : Très bon

Ville : Reims
Pays : France métropolitaine

 Les noms en anglais sont même mieux que les français.
Sinon c'est un excellent tuto, comme d'habitude. :)
Nous avons eu la gentillesse de vous répondre, ayez la gentillesse de mettre votre topic en Image utilisateur résolu !
 
Hors ligne casimirdeh # Posté le 09/02/2011 à 17:47:58

Y a-t-il un logiciel gratuit (au moins pour les étudiants ^^, de type VisualStudio) qui indente automatiquement sur demande.
C'est assez énervant de devoir tout décaler si on rajoute une condition sur toute un groupe d'instructions...
Merci.

Autrement, vraiment bravo et merci pour tout le travail réalisé sur ce site.
Hors ligne Bazar # Posté le 07/03/2011 à 16:28:07
Android
Avatar

Avis : Mitigé

Notepad++, tu sélectionnes l'ensemble du code à indenter, et Maj + Tab.
Bazar ^^
 

Voir tous les commentaires