Connaissez-vous la différence entre standards de codage et conventions de codage ? Les conventions organisent les instructions de programmation dans un script (par exemple: tabulation ou espaces ? ) alors que les standards sont relatifs à l'organisation générale d'une application. Sans quelques standards, n'importe qui peut faire n'importe quoi, n'importe comment. C'est probablement l'une des lacunes qui empêche encore la progression du PHP notamment en entreprise...

Robert Peake publie un long monoblogue de 3 articles consacré aux standards de codage. Il y plaide pour la répartition suivante :

  • Documentation automatique
  • Séparation du code de la présentation
  • Séparation du code et du contenu

Documentation automatique

La documentation est une partie fondamentale dans un projet mais reste encore trop souvent négligée. Commenter pertinemment le code est pourtant fondamental tant pour la maintenance et les développements ultérieurs que pour la réutilisation du code.

Certains extrémistes de la programmation pourraient prétendre qu'un programme bien commenté n'a pas besoin d'une documentation supplémentaire. J'imagine pourtant que tout le monde n'est pas disposé à éplucher le code source d'une application - pour autant qu'il soit accessible - pour en extraire une documentation. Spécialement en vue de pouvoir se servir d'une API.

La solution tient alors en un mot : PHPDocumentator.

Comme son parent JavaDoc, PhpDoc doit permettre de générer automatiquement une documentation hypertexte sur base des commentaires adéquatement laissés tout au long du code source. Ainsi, d'une part on dispose d'une documentation à jour et d'autre part PhpDoc impose une rigueur minimale dans l'élaboration des commentaires.

Faites comme moi : laissez-vous séduire par PhpDoc. Et place aux commentaires !