Commentaires de modification standard

Question

Je cherche une direction quant à un format standard pour commenter les changements dans PHP. Continuellement tout en travaillant avec un assortiment de développeurs sur des projets à grande échelle, les commentaires se déchaînent et dans la plupart des cas les changements sont soit mal commentés, soit pas commentés du tout.

est un exemple ici, s'il vous plaît ne hésitez pas à développer ce:

 
/** 
* Author: [first and last name] 
* Date Changed: [YYYY-MM-DD] 
* Description: [description] 
*/ 

Q: Est-ce que quelqu'un sait d'une manière standardisée de commenter les changements en PHP?

Answer 1

De telles choses ne doivent pas être placées dans les commentaires. Utilisez revision control software pour stocker toutes les versions de votre fichier (pas seulement les dernières). Ne permettez jamais aux développeurs de travailler sans cela. Un tel logiciel vous permet de faire beaucoup plus avec le code source:

• Vous pouvez trouver qui a changé chaque ligne du fichier
• Vous pouvez revenir fichier précédent (ou de travail) Version
• Vous pouvez créer les différentes branches de source et de les fusionner automatiquement
• vous pouvez automatiser la construction de votre logiciel et exécuter des tests automatiquement
• votre sauvegarde du référentiel source et vous ne serez jamais perdu votre travail
• ... and more

Answer 2

En plus d'utiliser le contrôle des sources, les commentaires doivent généralement se concentrer sur l'état actuel du code source, ne pas fournir l'histoire détaillée, sauf peut-être pour le contexte explicatif.

Les commentaires doivent décrire la façon dont et pourquoi d'un programme et ne pas être un scratchpad administratif ou de remplissage sous forme historique. C'est ainsi qu'un ingénieur communique avec un autre ingénieur - ou se rappelle peut-être - ce qu'est le modèle conceptuel. Cela pourrait expliquer la base d'une implémentation telle que sa philosophie, son utilisation prévue ou sa vision du monde. Mais, comme vous le savez bien, les ingénieurs ne peuvent pas être considérés comme des commis.

Je pense que nous avons tous vu la source comme ceci:

/* 
* Function: (fill in name) 
* 
* Returns: (fill in type) 
* 
* Date: (current date) 
* 
* Revision (revision number) 
* 
* Author: (your name or initials) 
* 
* Description: 
* (describe function) 
*/ 

où personne n'a rempli aucune mais les détails, si les plus inutiles à tous.