Dans l’article n°1 nous avons vus la liste des erreurs de développement les plus communes rencontrées dans les applications webs PHP. Dans les articles suivants nous allons revenir sur chacune d’entre elles avec un peu de détails quand celà est nécessaire.
7) Ne pas commenter votre code
Si vous êtes un professionnel en informatique et que vous avez déjà côtoyé des développeurs, vous le savez … Du code non commenté c’est presque impossible à maintenir. Nous le répéterons jamais assez, “Ne pas commenter c’est MAL” Partant de cette base, on pourrait penser que c’est un principe généralement suivit et que tous les développeurs le suivent … Oui mais voilà dans la vie réelle (ou du moins dans notre travail), il n’est par rare de tomber sur du code absolument non documenté. Voici quelques principes à respecter pour un code maintenable, reprennable et moderne :
- README dans le répertoire racine du projet : Donnera une idée du but du projet, une bref vision macro du fonctionnement, de comment l’installer, et toutes les subtilités à connaitre.
- Commentaires en début de fichier : Donne dans les grandes lignes le fonctionnement du script, de la classe etc…
- Commentaires en début de fonction : Décrit le but, les paramètres et les valeurs de retours
Idéalement, tous les fichiers doivent être commentés, que ce soit du code, des fichiers de configuration etc … Voici quelques liens sur le sujet :
Pour aller (beaucoup) plus loin : Aujourd’hui il existe des technologies beaucoup plus puissantes basées sur le commentaire de code.
- PHPdoc : permet de générer automatiquement une documentation basée sur vos commentaires sur tout code que vous souhaitez livrer ou exposer comme web service (API)
- Doxygen : permet entre autre de générer la documentation de vos classes, basée sur vos commentaires des fichiers. Il est devenu un standard du marché. (voir exemples)