Я не знаю про інші середовища, але коли мова йде про великі (часто з відкритим кодом) PHP-проекти, про які писали інші люди, phpXRef - це абсолютна економія життя (особливо якщо документ розміщено в Інтернеті і Google може його індексувати).
Навіть погано коментований проект може принаймні допомогти мені відстежити, де були визначені речі та де вони використовуються (наприклад, при рефакторингу).
Коли це добре прокоментовано, сторінки, що отримують результат, близькі до ідеальної Біблії для кодової бази (для мого використання в будь-якому випадку).
Крім того, мій кращий IDE автоматично генерує блок коментарів (якщо я набираю / **), що робить приблизно 75% роботи коментування для мене. Дивовижно, скільки дурних речей я не зупинив у вчиненні протягом свого кодерного життя лише тому, що мені довелося пояснювати іншим людям (і майбутнім мені), що я роблю. Коли мій коментар до генератора doc більше, ніж метод, зазвичай це означає, що мені не вистачало кави і, можливо, захочеться подумати трохи важче.
Ці самі ж коментарні блоки також створюють текст "довідки" вбудованого завершення вбудованого тексту, щоб я міг точно бачити, що очікувалося (від інших кодерів) під час написання виклику функції. Це значне підвищення продуктивності для мене (особливо у тих рідкісних випадках, коли якийсь інший корисний розробник написав "на користь заради робити / робити-не X" - це може врятувати багато болю.
Я не можу наголосити достатньо, наскільки корисно вказати очікувані типи вводу, вказані в складних (і часто неправильно названих) проектах PHP та порядку аргументів у менш часто використовуваних методах. Навіть маючи власний код, я не завжди можу згадати, які аргументи я вказав на те, чого я не торкався в епоху.
В одному випадку це означало, що джерелом повторюваних проблем було те, що з певних причин, які погано відображаються на попередніх розробниках, деякі функції і навіть константи були визначені у величезній кількості місць (зі ступенем неузгодженості для додаткової "забави") . Це був знак піти від проекту.
У більш великих проектах, які розпочалися ще до того, як я приєднався, я можу побачити, який розробник (якщо припустити, що вони позначили файл класу іменем та електронною поштою) створив клас, і просто можливість знайти та поговорити з потрібним розробником дуже корисно.
Автоматичні списки завдань - використання тегу @todo (поширеного для проектів, в яких я можу працювати) означає, що документація може відслідковувати речі, які потребують певної роботи (або функції, за якими визнано відсутні). Знову мій ІДЕ відслідковує це, і тільки воно є хорошим посібником щодо того, що в першу чергу потребує моєї уваги.
Нарешті (і це дуже важливо для мене), він знімає нетривіальне накладне написання всього цього, а потім намагається оновлювати його, коли деякі (читають багато) кодери здійснюють зміни і не спілкуються з керівниками документації.
Отже, причини:
- Заощаджуючи пізніших розробників масу часу,
- Відстежуючи, де функції називаються (і визначаються),
- Точкове кодування,
- Виявлення (як інший зазначав), коли чогось очевидно не вистачає,
- Спрощення рефакторингу (ніколи не дуже весело)
- (У багатьох випадках) отримання уявлення про те, що розробник намагався зробити (припускаючи, що він залишив нотатки).
- Якщо проект достатньо складний, щоб мати декілька ліцензій (без задоволення), я можу швидко побачити, які ліцензії застосовуються до будь-якого розділу. Справді, це боковий бонус.
- Отримання уявлення про те, з ким поговорити про файл проекту.
- Автоматичні списки завдань
Крім того, не варто недооцінювати цінність задоволення гострих шефів щасливим натисканням кнопки.
Коротше кажучи, "коментарі щодо автоматичної документації" є життєво важливими для моїх звичок кодування. Я впевнений, що є багато хто думає, що це кульгаво, але я також так само впевнений, що є небагато людей, які точно знають, про що я говорю. Я не знаю, як я вижив, перш ніж відкрити phpXRef (і моє улюблене IDE).