Является ли многословие PHPDoc большей проблемой, чем оно того стоит?[закрыто]

Question

Сегодня я впервые попробовал использовать PHPDoc и быстро столкнулся с проблемой.

На каждую 1 строку объявления переменных у меня было не менее 5 строк комментариев.Пример:

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

Конечно, отдача приятная, но это превращает 10-строчный конфигурационный файл в 60-строчный файл.У меня уходит целая вечность на заполнение, и я еще не уверен, что это так много добавляет по сравнению с простым однострочником.

Это также вносит излом в мой рабочий процесс.Все прекрасно до тех пор, пока мне не понадобится внести радикальные изменения.С моими хорошо документированными doc-блоками мне внезапно больше не нужно рефакторинговать свой код, но мне нужно переписать все эти утомительные детали.Ждать до конца, ты говоришь?ХАХ!Тогда документирование никогда не произойдет.

Вдобавок ко всему - это вынуждает меня использовать комментарии в стиле C / **/ в середине моего кода.Это сводит меня с ума во время разработки, поскольку лишает возможности комментировать большие блоки по требованию.Теперь, чтобы закомментировать большой блок кода, мне нужно вывести что-то вроде:range,s / ^/#/ ;тогда отмените это позже.Раздражает!

Короче говоря, мне нравится PHPDoc, я люблю хорошо документированный код, но 5 строк комментариев к каждой строке кода - это слишком много!.Есть ли какие-то функции, которых мне не хватает?Является ли это распространенной проблемой?

Answer 1

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

Например, прямо сейчас я работаю над проектом с довольно обширной базой кода, но очень небольшим количеством разработчиков (пока только я).Я добавляю блоки PHPDoc для двух целей:классы и методы.Что касается всего остального, я часто комментирую, но не в подробном формате PHPDoc.Большая часть этого кода будет видна только трем или четырем людям, и информация, которая им понадобится, - это информация из черного ящика:что я отправляю в этот метод, что я ожидаю получить от него.Они хотят знать, как получить данные из Модели, а не для чего предназначена частная переменная класса.

Если бы я писал приложение, которое намеревался распространять среди других разработчиков или компаний, и ожидал, что они интегрируют мое приложение с другими системами или расширят его функциональность, я бы придавал большее значение более широкому использованию PHPDoc.Такого рода детали определенно могут пригодиться при длительном техническом обслуживании.

Например, мой текущий проект в какой-то момент потребует создания API для доступа с других сайтов.Вы можете поспорить, что в API будет больше комментариев и письменной документации, чем строк кода.