Un code correctement commenté



Le dernier point, qui est 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. Mais 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 :

<?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 une à une les lignes de votre code ! Si j'ai insisté tout à l'heure pour que vous choisissiez des noms de variables et de fonctions clairs, c'est justement pour vous éviter d'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, on peut distinguer deux 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 de longs commentaires s'étalant sur plusieurs lignes.

   

Voici une petite illustration d'un code correctement commenté :

<?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 permet à l'auteur (moi ou un autre) de se repérer beaucoup plus facilement dans le code plus tard !

Créé avec HelpNDoc Personal Edition: Créer de la documentation iPhone facilement