La verbosité de PHPDoc représente-t-elle plus de problèmes qu'elle n'en vaut? [fermé]

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 cinq lignes de commentaires. Exemple:

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

Bien sûr, les gains sont intéressants - mais cela transforme un fichier de configuration de 10 lignes en un fichier de 60 lignes. Cela me prend une éternité à remplir, et je ne suis pas encore convaincu que cela ajoute autant à une simple ligne.

Cela crée également un problème dans mon flux de travail. Tout va bien et bien jusqu'à ce que je dois 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 je dois réécrire tous ces détails fastidieux. Attendez jusqu'à la fin, dites-vous? HAH! Ensuite, la documentation ne se produira jamais.

En plus de tout cela, cela me force à entrer des commentaires de style C / ** / au milieu de mon code. Cela me rend folle pendant le développement car elle empêche de commenter les gros blocs à la demande. Maintenant, pour commenter un gros bloc de code, je dois tirer quelque chose comme: range, s / ^ / # /; puis annulez-le plus tard. Ennuyeux!

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

Answer 1

Que ce soit excessif ou non 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 société ou un seul groupe, vous n'avez probablement pas besoin d'une documentation exhaustive de chaque variable.

Par exemple, je travaille actuellement sur un projet avec une base de code assez étendue mais très peu de développeurs (pour le moment, 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. La plupart de ce code ne sera jamais lu que par trois ou quatre personnes, et les informations dont elles auront besoin sont les informations de la boîte noire: qu'est-ce que j'envoie à cette méthode, qu'est-ce que je compte en retirer? Ils veulent savoir comment obtenir les données d'un modèle et non à 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 à d'autres sociétés et que je m'attendais à ce qu'elles intègrent mon application à d'autres systèmes ou étendent ses fonctionnalités, je mettrais davantage l'accent sur une utilisation plus étendue de PHPDoc. Ce genre de détail pourrait certainement être utile lors de la maintenance à long terme.

Exemple: mon projet actuel nécessitera à un moment donné la création d’une API accessible depuis d’autres sites. Vous pouvez parier que cette API aura plus de commentaires et de documentation écrite que de lignes de code.