Чи надлишкові шрифти docblock при використанні суворого введення тексту

У мене досить велика приватна база даних коду, яка розвивається вже близько десяти років. Я не використовую phpDocumentor, але оскільки використання розділів docblock стало цілком стандартним для проектів з відкритим кодом, я також прийняв написання docblocks для всіх публічних методів у моєму сховищі. Більшість блоків просто містять невеликий опис та підказки для всіх параметрів та типу повернення.

З приходом статичного аналізу ці типи підказки мені дуже допомогли знайти невідповідності та можливі помилки. Останнім часом я перетворив всю базу коду (зараз працює на PHP7.2), щоб мати всі параметри та повертати значення, наближені до типу, де це можливо, використовуючи typehints PHP. І тепер мені цікаво ... Чи не є ці шрифти docblock надлишковими? Це вимагає зовсім небагато роботи, щоб тримати всі docblocks в синхронізації з постійно мінливим кодом, і оскільки вони не додають ніякої нової інформації, мені цікаво, чи краще їх повністю видалити чи ні.

З одного боку, видалення документації відчуває себе погано, навіть коли воно зайве. В іншому, я дійсно відчуваю, як порушувати принцип "Не повторюй-повторюй сам" щоденний натяк на тип, що вже натякає на тип.

Інформація, яку можна знайти в коді, не повинна дублюватися в коментарях.

У кращому випадку витрачаються витрачені зусилля на підтримку їх синхронізації. Швидше за все, вони з часом вийдуть із синхронізації. У той момент вони просто плутають.

Якщо ви подивитеся на еквівалент DocBlock на мовах, що мають статичний характер (наприклад, Java, C #), ви побачите, що коментарі док не містять інформації про тип. Наскільки це стосується вашого PHP-коду, я б настійно радив дотримуватися відповідності. Звичайно, там, де не можна застосувати натяк на тип, коментар - це все-таки найкраща альтернатива.

Це не стосується PHP, але дублюється інформація про тип може мати сенс, коли тип неявно робиться (наприклад, Haskell).

Так, docblocks стали надлишковими для php 7.

Більшість часу в кодуванні витрачається на читання, тому необхідність прочитати одну і ту ж річ двічі впливає на вашу продуктивність. Крім того, це дозволяє легко пропустити важливі коментарі.

Я більше не пишу docblocks, за винятком випадків, коли хочу ввести натяк на масив певного типу (наприклад, @return int[]або @param SomeStatus[] $statusList) або коли я хочу додати коментар щодо методу, параметрів або повернутого значення. Мені здалося важливим відключити перевірку phpstorm, яка спрацьовує, коли у вас немає параметрів alle та повернення типів у docblock, якщо у вас є docblock.

Код і документація зазвичай мають різні аудиторії: документація призначена для користувачів цієї функції. Вони не повинні дивитись на код, щоб зрозуміти типи. Тому документація повинна містити всю необхідну інформацію, включаючи типи.

У деяких системах не потрібно вказувати тип параметра в документації, оскільки тип можна взяти з коду. PHPDoc - це не така система. Натомість @paramтег документально підтверджує це

Якщо вона надана, ОБОВ'ЯЗКОВО містити тип для вказівки того, що очікується

"Невелика робота над збереженням усіх docblocks у синхронізації з постійно змінюваним кодом" дещо скорочується, оскільки PHPDoc перевірятиме підказки типу документації щодо підказів типу коду. Це свого роду зв’язувальний / статичний аналіз, тому зробіть генерацію документації частиною вашого автоматизованого тестового конвеєра.

Ще одне запитання, яке ви можете задати собі, це те, чому ці функції задокументовані докладно, коли вони "постійно змінюються". Звичайна мотивація - створити посібник з HTML для своїх інтерфейсів. Але якщо документація ніколи не читається за межами IDE або якщо у вас немає стабільних інтерфейсів, де документація має сенс, то детальні docblocks є непотрібними або навіть оманливими. Можна краще написати лише резюме та відкласти повні документи, поки ви не дійшли до стабільного дизайну.