Project:Omega.org

Par John Coggeshall, le 07/10/2003

Traduit par Pascal pour Project:Omega.org, le 17/10/2003

Dans le précédent article, j’ai commencé cette série en décrivant un peu les erreurs de style les plus courantes et les plus sérieuses faites dans les scripts PHP. Dans cet article, je vais continuer en introduisant quelques bonnes idées qui rendront votre code plus professionnel et vous feront gagner un temps considérable et quelques maux de tête en moins. Commençons maintenant en décrivant une faute très courante dans de nombreux scripts PHP : La réinvention de la roue.

Les erreurs de style les plus courantes

Recommandation 4 : Ne pas réinventer la roue

Une des plus grosses erreurs non fatales que font les développeurs PHP quand ils écrivent des scripts est de tenter de réinventer la roue. Par exemple, ceci est une fonction qui découpe une longue chaîne à une certaine largeur de colonne pour l’afficher dans le navigateur ou un autre medium :

<?php
function textwrap($text, $wrap=80, $break='<br>') {
    $len = strlen($text);

    if ($len > $wrap) {
        $h         = '';
        $lastWhite = 0;
        $lastChar  = 0;
        $lastBreak = 0;

        while ($lastChar < $len) {
            $char = substr($text, $lastChar, 1);
            if (($lastChar - $lastBreak > $wrap)
            && ($lastWhite > $lastBreak)) {
                $h .= substr($text, $lastBreak,
                    ( $lastWhite - $lastBreak)) . $break;
                $lastChar  = $lastWhite + 1;
                $lastBreak = $lastChar;
            }

            /* Vous pourriez inclure d'autres caractères
                comme un espace blanc valide... */
            if ($char == ' ' || $char == chr(13) || $char == chr(10)) {
                $lastWhite = $lastChar;
            }
            $lastChar = $lastChar + 1;
        }
        $h .= substr($text, $lastBreak);
    }
    else{
        $h = $text;
    }
    return $h;
}?>

Est-ce une fonction utile et devant être disponible pour vos scripts ? Bien évidemment. Cependant, le temps passé à développer cette fonction a été gaché car PHP a déjà une fonction interne, wordwrap(), qui a exactement le même but. Rien n’est plus désolant, ou une pire perte de temps, que de perdre des heures à écrire du code pour accomplir une tâche et de découvrir plus tard qu’une fonction que vous essayez de développer existe déjà.

C’est toujours une meilleure idée d’utiliser ces fonctions intégrées dès que possible. Non seulement elles sont moins susceptibles d’être boguées que les vôtres, mais en plus elles contribuent à rendre votre code plus rapide à exécuter. Comme par hasard, j’ai trouvé beaucoup de fonctions existantes dont je me disais justement que cela serait une bonne idée qu’elles soient incorporées dans PHP, donc ne perdez pas de temps à écrire du code personnalisé avant d’avoir fouillé dans le manuel de PHP.

Recommandation 5 : Servez-vous de la syntaxe “heredoc”

Une des fonctionnalités les plus pratiques de PHP est la possibilité de placer du code HTML directement dans la structure du script. Le but de ce type de fonctionnalité est non seulement de produire plus facilement du code dynamique, mais aussi de produire du code plus propre. Dans certaines circonstances, cette aptitude peut être mal utilisée ou trop utilisée, aboutissant à quelques scripts particulièrement laids. Voici un exemple où l’utilisation de l’inclusion de code HTML apporte plus de problèmes que de valeur (considérez que toutes les variables sont bien définies) :

<a href="<? echo $url; ?>">
<font face="arial" size=<? if($bighead > 0) echo $size+1; else echo $size;  ?>>
<? if($bighead > 0) echo "<b>$headline</b>"; else echo $headline; ?></font>
</a>

Encore une fois, bien que cela fonctionne, il est très difficile de lire et de déterminer ce que fait exactement ce bout de code. Une meilleure alternative à ce problème est d’éviter d’inclure du HTML et d’utiliser à la place une fonction echo pour afficher cet hyperlien :

<?php
   echo "<a href="$url">" .
         "<font face="arial" size=" .
         (($bighead > 0) ? $size +1 : $size) . ">" .
         (($bighead > 0) ? "<b>$headline</b>" : $headline) .
         "</font></a>";
?>

Bien qu’un peu plus facile à lire, ce n’est pas encore très propre. Dans de telles situations, PHP offre une troisième alternative qui permet de combiner les avantages de la fonction echo et ceux de l’inclusion de code HTML, j’ai nommé : la syntaxe  “heredoc”. Les chaînes “heredoc” sont définies comme suit :

$variable = <<< IDENTIFIER
[Contenu de la chaîne]
IDENTIFIER;

IDENTIFIER est une chaîne conforme aux règles de toute variable PHP. Aussi, notez que le IDENTIFIER de fin (qui suit le contenu de la chaîne) doit être très strictement conforme aux recommandations pour que cela fonctionne correctement :

• le IDENTIFIER de fin doit apparaître sur sa propre ligne (NDT : je comprends TOUT SEUL)
• la chaîne IDENTIFIER ne doit pas être précédée ni suivie par un espace blanc comme une espace, une tabulation et caetera, excepté le caractère de nouvelle ligne (n)

Un bogue apparait souvent quand on utilise la syntaxe “heredoc” dans un éditeur de texte avec Windows. Le problème vient de l’utilisation par Windows d’une combinaison de deux caractères (rn) pour indiquer une nouvelle ligne. Comme les systèmes UNIX n’utilisent qu’un seul caractère (n) pour indiquer une nouvelle ligne, le retour de chariot (r) est considéré comme un espace blanc par PHP et cause souvent des problèmes avec “heredoc”. Tout éditeur de texte compatible Windows supportant UNIX fournit des solutions pour sauvegarder les fichiers avec seulement un caractère de fin de ligne, mais ne pas être au courant de ce problème rend presque impossible de s’en rendre compte.

Quand on utilise la syntaxe “heredoc”, la chaîne placée dans $variable se comportera exactement de la même manière que si elle était entre guillemets. Elle sera analysée et toutes les variables référencées seront remplacées. Toutefois, il n’y a aucun besoin d’échapper les caractères, les guillemets par exemple, comme cela serait nécessaire en travaillant avec des chaînes standards. Pour voir comment est utilisée la syntaxe “heredoc”, voici comment réécrire l’exemple montré plus haut :

if($bighead > 0) {
    $link_size = $size +1;
    $link_html = "<b>$headline</b>";
} else {
    $link_size = $size;
    $link_html = $headline;
} 

echo <<< HTML_LINK
<a href="$url"><font face="arial" size=$link_size>$link_html</font></a>
HTML_LINK;

Comme c’est le cas avec l’inclusion de code HTML, “heredoc” peut être utilisé à mauvais escient. Cependant, dans ce cas, l’utilisation de “heredoc” a rendu votre code plus lisible et c’était un bon choix. Utiliser votre bon sens pour choisir la méthode qui fonctionne le mieux dans votre situation est un aspect important de l’écriture d’un code qui soit professionnel et facile à comprendre.

Recommandation 6 : Nommez vos fonctions et vos variables de manière appropriée

Toute cette présentation a été conduite dans le but d’écrire du code facile à comprendre. Peut-être que la technique la plus importante est de nommer vos fonctions de manière appropriée. Par exemple, regardez ci-après l’appel à une fonction définie par l’utilisateur :

<?php
$c = snews('O', 80, 7, 4, 2, 1);
echo $c;
?>

Avez-vous la moindre idée de ce que peut faire cette fonction ? Elle semble avoir à faire quelque chose avec des nouvelles (news) d’une sorte particulière. Peut-être qu’elle sauvegarde les nouvelles ? Que veulent dire les paramètres ? Que contient la valeur retournée ? Malheureusement, il n’y a aucun moyen de dire quoi que ce soit de ce bout de code.

En réalité, cette fonction a été utilisée pour afficher une table HTML formatée représentant les dernières nouvelles d’un site. Malheureusement, le script auquel appartient cette ligne a été très mal structuré. Lorsque vos scripts deviennent de plus en plus complexes, il devient essentiel de décrire très clairement à la fois les variables que vous utilisez et les fonctions qui les utilisent. Il y a plusieurs manières de le faire.

Pour commencer, il est toujours bon de donner des noms descriptifs aux variables et aux fonctions. Le nom devrait permettre à une tierce personne qui ne connaît rien de votre script d’avoir une assez bonne idée de ce que fait une fonction ou une variable au cas où aucune documentation n’est disponible (bien que vous devriez toujours documenter le code important). Vous pouvez ne pas respecter cette règle dans une seule situation : quand vous utilisez des variables temporaires pour une boucle ou quelque chose comme cela. Même dans ces cas là, un nom de variable avec une seule lettre devrait être évité. Si notre fonction exemple avait été nommée shownews(), ou, encore mieux, create_news_table() même quelqu’un qui ne connaît rien du script pourrait faire des hypothèses raisonnables quand à son utilité. Les mêmes concepts s’appliquent à la description de vos variables. Si la variable $c avait été nommée $content, ou même $news_table_content, vous auriez su exactement ce que cette variable est sensée contenir après l’exécution de la fonction.

Dans le cas où vous passez ou utilisez des constantes dans vos scripts PHP, c’est tout simplement une mauvaise idée de les utiliser elles-mêmes directement. Encore une fois, que représentent exactement les valeurs 'O', 80, 7, 4, 2, et 1 dans cette appel de fonction ? Malheureusement, il n’y a aucun moyen de le dire. Une meilleure solution serait d’utiliser la fonction PHP define() pour définir des constantes nommées puis de les utiliser quand c’est nécessaire:

<?php
    define('NEWS_GRP_OTHER', 'O');
    define('NEWS_MAX_COLUMNS', 80);
    define('NEWS_MAX_ROWS', 7);
    define('NEWS_MAX_ARTICLES', 2);
    define('NEWS_FONT_SIZE', 1);

    snews(NEWS_GRP_OTHER,
          NEWS_MAX_COLUMNS,
          NEWS_MAX_ROWS,
          NEWS_MAX_ARTICLES,
          NEWS_FONT_SIZE); 

?>

L’appel de fonction est déjà plus facile à comprendre. La fonction de chaque paramètre est maintenant claire. Il peut être modifié en toute confiance. De même, si vous voulez changer le nombre maximum de lignes par article, il n’est pas besoin de changer une valeur partout dans le script; au lieu de cela, il n’y a qu’à changer la valeur donnée dans la fonction define(). Pour rendre vos scripts encore plus propres, toutes les déclarations “define” de ce script peuvent aussi être stockées dans un fichier séparé et inclus dans le script. Evidemment, cette méthode est la plus professionnelle et est fortement recommandée à chaque fois que des constantes sont utilisées.

Intégrons tout cela maintenant. Vous serez seul juge pour déterminer si une tierce personne pourrait comprendre ce que ce bout de code fait (considérons que les constantes ont été définies dans le fichier inclus) :

<?php
    include_once('constants.php');

    $news_table_html = create_news_table(NEWS_GRP_OTHER,
                                         NEWS_MAX_COLUMNS,
                                         NEWS_MAX_ROWS,
                                         NEWS_MAX_ARTICLES,
                                         NEWS_FONT_SIZE); 

    echo $news_table_html;
?>

Conclusion

Ceci conclut le deuxième article de ma série sur la “Paranoïa en PHP”. J’espère que vous comprenez l’importance de prendre de bonnes pratiques et habitudes quand vous écrivez vos scripts. Ce n’est pas un euphémisme que de prétendre qu’adopter ces pratiques réduira significativement le nombre de problèmes et de bogues qui apparaîtront dans vos scripts. Et vous les trouverez plus faciles à maintenir.

Textes originaux en anglais sur O’Reilly : Common Styles Mistakes, part 2 par John Coggeshall

Pascal Développement Web Mac OS X, PHP