Les indices de type docblock sont-ils redondants lors de l'utilisation d'une frappe stricte

J'ai une base de code privée assez importante qui a évolué depuis une dizaine d'années maintenant. Je n'utilise pas phpDocumentor mais depuis que l'utilisation des sections docblock est devenue tout à fait la norme dans les projets open source, j'ai également adopté l'écriture de docblocks pour toutes les méthodes publiques dans mon référentiel. La plupart des blocs contiennent juste une petite description et des indications de type pour tous les paramètres et le type de retour.

Avec l'arrivée de l'analyse statique, ces typographies m'ont beaucoup aidé à trouver des incohérences et des bugs possibles. Dernièrement, j'ai converti l'intégralité de la base de code (en cours d'exécution sur PHP7.2) pour que tous les paramètres et les valeurs de retour soient indiqués dans la mesure du possible, en utilisant les indications de type de PHP. Et maintenant, je me demande ... Est-ce que ces caractères de type docblock ne sont pas redondants? Cela demande un peu de travail pour garder tous les docblocks en synchronisation avec le code en constante évolution et comme ils n'ajoutent aucune nouvelle information, je me demande s'il est préférable de les supprimer complètement ou non.

D'une part, la suppression de la documentation est mauvaise, même lorsqu'elle est redondante. Dans l'autre, j'ai vraiment envie de briser le principe de ne pas répéter soi-même tous les jours qui donne déjà un indice.

Les informations qui peuvent être trouvées dans le code ne doivent pas être dupliquées dans les commentaires.

Au mieux, c'est un effort inutile pour les garder synchronisés. Plus probablement, ils finiront par se désynchroniser. À ce stade, ils sont tout simplement déroutants.

Si vous regardez l'équivalent DocBlock dans des langages typés statiquement (par exemple Java, C #), vous constaterez que les commentaires doc ne contiennent pas d'informations de type. Dans la mesure où c'est le cas dans votre code PHP, je vous conseille fortement de faire de même. Bien sûr, lorsque l'indication de type ne peut pas être appliquée, un commentaire est toujours votre meilleure alternative.

Cela n'est pas pertinent pour PHP, mais les informations de type dupliquées peuvent avoir un sens lorsque le type est implicitement déduit (par exemple Haskell).

Oui, les docblocks sont devenus redondants avec php 7.

La plupart du temps dans le codage est consacré à la lecture, donc avoir à lire deux fois la même chose a un impact sur votre productivité. De plus, il est facile de manquer des commentaires réellement importants.

Je n'écris plus de docblocks, sauf quand je veux taper hint un tableau d'un certain type (par exemple @return int[]ou @param SomeStatus[] $statusList) ou quand je veux ajouter un commentaire sur la méthode, les paramètres ou la valeur de retour. J'ai trouvé important de désactiver l'inspection phpstorm qui se déclenche lorsque vous n'avez pas tous les paramètres et renvoyez les types dans un docblock si vous avez un docblock.

Le code et la documentation ont généralement des publics différents: la documentation est destinée aux utilisateurs de cette fonction. Ils ne devraient pas avoir à regarder le code pour comprendre les types. Par conséquent, la documentation doit inclure toutes les informations nécessaires, y compris les types.

Dans certains systèmes, il n'est pas nécessaire de spécifier un type de paramètre dans la documentation car le type peut être extrait du code. PHPDoc n'est pas un tel système. Au lieu de cela, la @parambalise est documentée que

Lorsqu'il est fourni, il DOIT contenir un type pour indiquer ce qui est attendu

Le «pas mal de travail pour synchroniser tous les docblocks avec le code en constante évolution» est quelque peu réduit car PHPDoc vérifiera les indications de type de documentation par rapport aux indications de type de code. Il s'agit d'une sorte d'analyse statique / statique, alors intégrez votre génération de documentation à votre pipeline de test automatisé.

Une autre question que vous voudrez peut-être vous poser est la raison pour laquelle ces fonctions sont documentées dans ce détail lorsqu'elles sont «en constante évolution». La motivation habituelle est de créer un manuel de référence HTML de vos interfaces. Mais si la documentation n'est jamais lue en dehors d'un IDE, ou si vous n'avez pas d'interfaces stables où la documentation a du sens, alors les blocs de documentation détaillés sont inutiles, voire trompeurs. Il peut être préférable d'écrire uniquement un résumé et de différer les documents complets jusqu'à ce que vous soyez parvenu à une conception stable.