Избыточные шрифты докблока избыточны при использовании строгой типизации

У меня довольно большая частная кодовая база, которая развивается уже около десяти лет. Я не использую phpDocumentor, но поскольку использование разделов с докблоком стало довольно стандартным в проектах с открытым исходным кодом, я принял написание докблоков для всех открытых методов в моем репозитории. Большинство блоков просто содержат небольшое описание и подсказки для всех параметров и типа возвращаемого значения.

С появлением статического анализа эти шрифты очень помогли мне найти несоответствия и возможные ошибки. В последнее время я преобразовал всю кодовую базу (теперь работающую на PHP7.2), чтобы все параметры и возвращаемые значения были, по возможности, подсказаны типами, используя шрифты PHP. А теперь мне интересно ... Разве эти docblock-шрифты не избыточны? Требуется немало усилий, чтобы синхронизировать все docblocks с постоянно меняющимся кодом, и, поскольку они не добавляют никакой новой информации, я задаюсь вопросом, лучше ли их полностью удалить или нет.

С одной стороны, удаление документации плохо, даже если это излишне. С другой стороны, я действительно чувствую, что ломаю повседневные вещи типа хинтинга по принципу «не повторяй себя», которые уже намекают на тип.

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

В лучшем случае это бесполезная попытка синхронизировать их. Скорее всего, они со временем потеряют синхронизацию. В этот момент они просто сбивают с толку.

Если вы посмотрите на эквивалент DocBlock в статически типизированных языках (например, Java, C #), то обнаружите, что комментарии к документу не содержат информацию о типе. Поскольку это имеет место в вашем PHP-коде, я настоятельно рекомендую последовать его примеру. Конечно, там, где намеки на тип не могут быть применены, комментарий по-прежнему является вашей лучшей альтернативой.

Это не относится к PHP, но дублированная информация о типе может иметь смысл, когда тип выводится неявно (например, Haskell).

Да, docblocks стали избыточными с php 7.

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

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

Код и документация обычно имеют разную аудиторию: документация предназначена для пользователей этой функции. Им не нужно смотреть на код, чтобы понять типы. Поэтому документация должна включать в себя всю необходимую информацию, включая типы.

В некоторых системах нет необходимости указывать тип параметра в документации, поскольку этот тип можно взять из кода. PHPDoc не такая система. Вместо этого @paramтег задокументирован, что

При условии, что он ДОЛЖЕН содержать тип, указывающий, что ожидается

«Довольно много работы для синхронизации всех docblocks с постоянно изменяющимся кодом» несколько сокращено, потому что PHPDoc будет проверять подсказки типа документации по подсказкам типа кода. Это своего рода статический анализ, поэтому сделайте генерацию документации частью вашего автоматизированного конвейера тестирования.

Другой вопрос, который вы, возможно, захотите задать себе, заключается в том, почему эти функции подробно описаны в этих деталях, когда они «постоянно меняются». Обычной мотивацией является создание справочного руководства по HTML ваших интерфейсов. Но если документация никогда не читается за пределами IDE, или если у вас нет стабильных интерфейсов, в которых документация имеет смысл, то подробные блоки документации не нужны или даже вводят в заблуждение. Может быть лучше написать только резюме и отложить полные документы, пока вы не получите стабильный дизайн.