Bonnes pratiques PHP : documentez votre code

Directement inspiré de Javadoc, PHPDoc vous propose d'intégrer votre documentation directement dans votre code sous la forme de commentaires à la syntaxe normalisée. La bonne habitude à prendre est d'écrire ces commentaires en même temps que votre code, limitant l'augmentation de la charge de travail liée à la production de cette documentation.

Arrivé cette année dans sa version 2, qui supporte PHP 5.3 et ultérieurs, phpDocumentor est l'un des outils de génération de documentation s'appuyant sur PHPDoc, et c'est celui avec lequel nous allons travailler ici, en nous appuyant sur son implémentation de PHPDoc, mais rien ne vous empêche de lui préférer Doxygen.

Cerise sur le gâteau : si vous utilisez un bon IDE pour saisir votre code, celui-ci sera capable de s'appuyer également sur PHPDoc pour vous assister plus efficacement.

Un bémol toutefois : la documentation automatique est destinée aux développeurs de l'application et certainement pas à ses…