Je ne connais pas les autres environnements, mais lorsqu'il s'agit de grands projets PHP (souvent open source) écrits par d'autres personnes, phpXRef est un épargnant de vie absolu (surtout si le document est mis en ligne et que Google peut l'indexer).
Même un projet mal commenté peut au moins m'aider à localiser les éléments définis et leur utilisation (par exemple lors de la refactorisation).
Lorsqu'elles sont bien commentées, les pages résultantes forment presque une Bible parfaite pour le code base (pour mes utilisations de toute façon).
De plus, mon IDE préféré générera automatiquement le bloc de commentaires (si je tape / **), qui effectue environ 75% du travail de commentaire pour moi. Il est étonnant de constater combien de choses stupides qui m'ont empêché de commettre au cours de ma vie de codeur simplement parce que j'ai dû expliquer à d'autres personnes (et à moi futur) ce que je faisais. Lorsque mon commentaire pour le générateur de doc est plus important que la méthode, cela signifie généralement que je n'ai pas assez de café et que je souhaite peut-être réfléchir un peu plus fort.
Ces mêmes blocs de commentaires créent également le texte "aide" de l'achèvement en ligne afin que je puisse voir exactement ce qui était attendu (par les autres codeurs) au moment où j'écris l'appel de fonction. Cela représente un gain de productivité considérable pour moi (en particulier dans les cas rares où un autre développeur utile a écrit "pour l'amour du bien, do / do-not X" - ce qui peut éviter beaucoup de douleur.
Je ne saurais trop insister sur l’utilité d’avoir les types d’entrée attendus spécifiés dans des projets PHP complexes (et souvent mal nommés) et l’ordre des arguments dans des méthodes moins fréquemment utilisées. Même avec mon propre code, je ne peux pas toujours me souvenir des arguments que j'ai spécifiés pour quelque chose que je n'ai pas touché dans une époque.
Dans un cas, cela signifiait que la source des problèmes récurrents était que, pour une raison qui reflétait mal les développeurs précédents, certaines fonctions et même des constantes étaient définies dans un très grand nombre d'endroits (avec un certain degré d'incohérence pour plus de "plaisir") . C'était le signe de s'éloigner du projet.
Dans les projets plus importants qui ont commencé avant que je rejoigne, je peux voir quel développeur (en supposant qu'ils aient balisé le fichier de classe avec un nom et un email) a créé la classe et pouvoir simplement trouver et parler au bon développeur est extrêmement utile.
Listes de tâches automatiques - l'utilisation de la balise @todo (courante dans le type de projet dans lequel je me trouve) signifie que la documentation peut garder trace de choses qui nécessitent un travail supplémentaire (ou de fonctionnalités manquantes). Encore une fois, mon IDE garde la trace de ceci et cela seul est un bon guide pour ce qui nécessite mon attention en premier.
Enfin (et très important pour moi), cela supprime la surcharge non triviale d'écrire tout cela, puis d'essayer de le garder à jour lorsque certains (lisent beaucoup) des développeurs engagent des modifications et ne parlent pas aux responsables de la documentation.
Donc, les raisons incluent:
- Économie de temps pour les développeurs ultérieurs,
- Garder une trace de l'endroit où les fonctions sont appelées (et définies),
- Repérer un code idiot,
- Trouver (comme un autre l’a fait remarquer) quand quelque chose manque manifestement,
- Simplifier la refactorisation (jamais très amusant)
- (Dans de nombreux cas) avoir une idée de ce que le développeur essayait de faire (en supposant qu'il ait laissé des notes).
- Si le projet est suffisamment complexe pour avoir plusieurs licences en cours (pas amusant), je peux rapidement voir quelles licences s'appliquent à une section donnée. Certes, c'est un bonus supplémentaire.
- Obtenir une idée de qui parler à un fichier de projet.
- Listes de tâches automatiques
Ne sous-estimez pas non plus l’importance de garder heureux les patrons aux cheveux pointus par simple pression sur un bouton.
En bref, les "commentaires de documentation automatique" sont essentiels à mes habitudes de codage. Je suis sûr que beaucoup pensent que c'est boiteux, mais je suis tout aussi convaincu qu'il y a assez peu de gens qui savent exactement ce que je dis. Je ne sais pas comment j'ai survécu avant de découvrir phpXRef (et mon IDE préféré).