La verbosité de PHPDoc est-elle plus problématique qu'elle n'en vaut la peine?

Question

J'ai essayé d'utiliser PHPDoc pour la première fois aujourd'hui et j'ai rapidement rencontré un problème.

Pour chaque ligne de déclarations de variables, j'avais au moins 5 lignes de commentaires. Exemple:

/** 
* Holds path the remote server 
* @name ... 
* @global ... 
*/ 
$myvar = ... 

Bien sûr, les gains sont bien - mais cela tourne un fichier de configuration 10 en ligne dans un fichier 60 en ligne. Ça me prend une éternité à remplir, et je ne suis pas encore convaincu que cela ajoute autant à un simple interligne.

Cela jette aussi un kink dans mon flux de travail. Tout va bien et bien jusqu'à ce que j'ai besoin de faire des changements radicaux. Avec mes doc-blocks bien documentés, tout d'un coup je n'ai plus besoin de refactoriser mon code, mais j'ai besoin de réécrire tous ces détails fastidieux. Attendez jusqu'à la fin que vous dites? HAH! Alors la documentation n'arrivera jamais. En plus de tout cela - il me force dans C-style/**/commentaires au milieu de mon code. Cela me rend fou pendant le développement car il enlève la possibilité de commenter de gros blocs à la demande. Maintenant, pour commenter un grand bloc de code, j'ai besoin de tirer quelque chose comme: range, s/^/# /; puis défaites-le plus tard. Ennuyeux!

Longue histoire courte - J'aime PHPDoc, j'adore le code bien documenté - mais 5 lignes de commentaires pour chaque ligne de code est beaucoup trop de !. Y a-t-il des fonctionnalités qui me manquent? Est-ce un problème courant?

Answer 1

La surutilisation dépend en grande partie de l'utilisation prévue de votre application. Si vous écrivez une application qui ne sera utilisée que par une seule entreprise ou un seul groupe, vous n'avez probablement pas besoin d'une documentation exhaustive de chaque variable. Par exemple, en ce moment je travaille sur un projet avec une base de code assez étendue mais très peu de développeurs (pour l'instant, juste moi). J'ajoute des blocs PHPDoc pour deux choses: les classes et les méthodes. Pour tout le reste, je commente fréquemment, mais pas au format PHPDoc verbeux. La plupart de ce code ne sera jamais vu que par trois ou quatre personnes, et l'information dont ils auront besoin est la boîte noire: qu'est-ce que j'envoie à cette méthode, qu'est-ce que je m'attends à en sortir. Ils veulent savoir comment obtenir des données à partir d'un modèle, pas à quoi sert une variable de classe privée. Si j'écrivais une application que j'avais l'intention de distribuer à d'autres développeurs ou entreprises, et que je m'attendais à ce qu'ils intègrent mon application avec d'autres systèmes ou étendent ses fonctionnalités, j'accorderais plus de valeur à une utilisation plus étendue de PHPDoc. Ce genre de détail pourrait certainement être utile lors de la maintenance à long terme. Par exemple, mon projet actuel nécessitera à un moment donné la création d'une API accessible à partir d'autres sites. Vous pouvez parier que l'API aura plus de commentaires et de documentation écrite que des lignes de code.