Я не знаю о других средах, но когда дело доходит до больших (часто с открытым исходным кодом) проектов PHP, которые написали другие люди, phpXRef является абсолютным спасением жизни (особенно, если документ размещен в Интернете, и Google может его проиндексировать).
Даже плохо прокомментированный проект может, по крайней мере, помочь мне отследить, где вещи были определены и где они используются (например, при рефакторинге).
При правильном комментировании получающиеся страницы формируются близко к идеальной Библии для базы кода (в любом случае, для моего использования)
Кроме того, моя предпочтительная IDE автоматически сгенерирует блок комментариев (если я наберу / **), который выполняет для меня примерно 75% комментариев. Удивительно, сколько глупостей я не мог совершить за свою жизнь программиста только потому, что мне пришлось объяснять другим людям (и будущему мне), что я делаю. Когда мой комментарий к генератору документов больше, чем метод, это обычно означает, что мне не хватило кофе и, возможно, хотелось бы подумать немного сложнее.
Эти те же самые блоки комментариев также создают встроенный текст «помощи» для завершения, так что я могу точно видеть, чего ожидали (другие кодеры), когда я пишу вызов функции. Для меня это огромный прирост производительности (особенно в тех редких случаях, когда какой-то другой полезный разработчик написал «ради бога, делай / не делай Х»), что может спасти много боли.
Я не могу не подчеркнуть, насколько полезно указывать ожидаемые типы ввода в сложных (и часто плохо именуемых) проектах PHP и порядок аргументов в менее часто используемых методах. Даже с моим собственным кодом я не всегда могу вспомнить, какие аргументы я указывал для чего-то, чего я не коснулся в эпоху.
В одном случае это означало, что источником повторяющихся проблем было то, что по некоторым причинам, которые плохо отражаются на предыдущих разработчиках, некоторые функции и даже константы были определены в огромном количестве мест (со степенью несоответствия для добавленного «веселья») , Это был знак уйти от проекта.
В более крупных проектах, которые начались до того, как я присоединился, я могу видеть, какой разработчик (предполагая, что они пометили файл класса именем и адресом электронной почты) создал класс, и просто возможность найти подходящего разработчика и поговорить с ним чрезвычайно полезна.
Автоматические списки задач - использование тега @todo (часто встречается в проектах, над которыми я работаю) означает, что документация может отслеживать материалы, требующие дополнительной работы (или функции, которые признаны отсутствующими). Опять же, моя IDE отслеживает все это, и это само по себе служит хорошим руководством к тому, что в первую очередь требует моего внимания.
И наконец (и это очень важно для меня), он устраняет нетривиальные накладные расходы, связанные с записью всего этого, а затем пытается поддерживать его в актуальном состоянии, когда некоторые (читай многие) кодеры фиксируют изменения и не общаются с сопровождающими документации.
Итак, причины включают в себя:
- Экономя последним разработчикам кучу времени,
- Отслеживание того, где функции вызываются (и определяются),
- Обнаружение глупого кодирования,
- Нахождение (как указал другой), когда чего-то явно не хватает,
- Упрощение рефакторинга (никогда не очень весело)
- (Во многих случаях) получить представление о том, что разработчик пытался сделать (при условии, что он или она оставили некоторые заметки).
- Если проект достаточно сложный, чтобы иметь несколько лицензий (неинтересно), я могу быстро увидеть, какие лицензии применимы к любому данному разделу. Правда, это побочный бонус.
- Получить представление о том, с кем поговорить о файле проекта.
- Автоматические списки задач
Кроме того, не стоит недооценивать ценность того, чтобы держать боссов с острыми волосами счастливыми одним нажатием кнопки.
Короче говоря, «автоматические комментарии к документации» жизненно важны для моих привычек кодирования. Я уверен, что многие думают, что это глупо, но я также уверен, что есть немало людей, которые точно знают, что я говорю. Я не знаю, как я выжил до открытия phpXRef (и моей любимой IDE).