Коментування коду і генерація документації в php, блог
Варіанти розміщення документації
Давайте для початку розглянемо документацію за межами коду програми. Хоча це не є метою даної статті. У open source проектах нерідко зустрічається практика, коли статті по документації зберігаються в тому ж репозиторії, що і основний код. Наприклад, в бібліотеці для генерації фейковий фікстур для PHP документація поміщена в README файл; щоб дочитати до кінця, потрібно трохи поскроліть. Популярний HTTP-клієнт для PHP Guzzle зберігає інструкції по застосуванню в різних файлах в окремій папці docs. Зберігати документацію біля коду - це, звичайно, добре і зручно. Один раз скачавши пакет вендора, у вас є і код, і документація. Якщо ваша бібліотека невелика, якщо вона стабільна і не припускає в майбутньому постійних змін API, які спричинять за собою постійне переписування документації, тоді можете сміливо розміщувати документацію в репозиторії вашого проекту.
Опустимо реалізацію цього інтерфейсу, просто створимо новий об'єкт від класу Rabbit:
Rabbit - іменник, run - дієслово, in metres - контекст, який ми додаємо методу, щоб він передавав суть. Користуючись такою схемою, можна написати методи
Але ось це вже перебір:
Є, правда, і винятки в довжині назви методів. Наприклад, коли ви пишете спеки на phpSpec. то можете не обмежувати себе в довжині методу, головне, щоб він передавав всю суть. Ось приклад коду, взятого з документації phpSpec:
У спікся для назв методів використовується запис underscore. тому оці легше зачепитися за кордону слів і прочитати довге речення. Це не по стандарту PSR, де використовується camelCase. але для удобочитаемость тестів такий варіант підійде.
Почуття міри в назвах методів приходить з часом, з досвідом. Можна підглянути, як це роблять в популярних фреймворків і бібліотеках.
неактуальність
надмірність
недостовірність
неочевидність
Це коли в конкретному місці коду використовуються невідомої або не очевидні терміни.
Писати, але потрібно брати за них відповідальність. Ось моменти, коли вони необхідні.
інформативність
Одну і ту ж задачу на мові програмування можна вирішити багатьма способами. Програміст має власний стиль програмування і, знайомлячись з кодом іншого програміста, з іншим стилем, йому може бути важко прочитати код «по діагоналі». Якщо ви володієте якимось особливим стилем програмування, або з досвіду знаєте, що алгоритми, які ви використовуєте, важко Новомосковскются іншими, то залишайте в коді підказки безпосередньо перед початком складного ділянки коду.
попередження
Чи не документуйте поганий код - перепишіть його.
Документуємо за допомогою докблоков
Докблоком може бути і один рядок, головне, щоб вона починалася з / **.
Докблокі настільки прижилися в ком'юніті PHP-програмістів, що на їх основі готується PSR-5 (PHP Standard Recommendation). На момент написання статті він ще знаходився в чорновому варіанті.
У PHP за допомогою докблоков можна документувати такі елементи:
Важливо також, що один докблок може бути застосований лише до одного структурному елементу. Тобто на кожну функцію - свій докблок, на змінну всередині функції - свій, для класу - свій.
У PHPDoc існує багато тегів, але не кожен тег застосуємо до всіх структурних елементів. Нижче надано список існуючих тегів, область їх використання і пояснення.
Застарілі теги, які, швидше за все, в майбутньому не будуть підтримуватися:
- @category (файл, клас) - використовувався для групування пакетів разом.
- @subpackage (файл, клас) - використовувався для виділення певних груп в пакетах.
Не всі теги однаково популярні, найчастіше використовуються: @var, @param, @return, @todo, @throws. інші - рідше. А такі, як @property і @method я взагалі ще не зустрічав в застосуванні, тому що «працювати з магією» в PHP - небезпечно :)
Зручність використання докблоков в IDE
Якщо ви розробляєте open source проект, то звичайно документування публічного API за допомогою докблоков необхідно. Це не тільки дозволить вам згенерувати готову документацію, але також дозволить використовувати ваш код зручно іншим розробникам в своїх IDE. Що стосується вашого приватного коду для аутсорс проекту, то використання докблоков може здатися не дуже доречним, проте раджу їх використовувати, це значно прискорить вашу розробку.
Для прикладу візьмемо найпопулярнішу IDE для PHP - PhpStorm. Розглянемо попередній приклад пошуку кроликів:
Що зберігають в собі змінні $ rabbits і $ rabbit. PhpStorm про це нічого не знає. PHP - мова слабо типізований, тип результату функції не задається жорстко з її опису (привіт PHP7, де це буде реалізовано). Тому вашої IDE потрібно підказати за допомогою докблоков, як вести себе з тим чи іншим кодом. Варіантів є декілька. Можна зробити так:
Або додати тег @return в метод findRabbitsInLocations:
Зверніть увагу, що ми вказали Rabbit []. а не Rabbit. Квадратні дужки дають зрозуміти, що повертається масив об'єктів класу Rabbit. якщо квадратні дужки прибрати, то це буде означати, що метод повертає один екземпляр класу Rabbit. Ще можна написати так @return null | Rabbit []. вертикальна палиця означає «АБО», в даному випадку ми вказуємо, що метод поверне або масив кроликів, або null.
Незалежно від того, який спосіб вказівки типу ви вибрали, PhpStorm тепер видаватиме вам підказки, коли ви надрукуєте $ rabbit-> і почекаєте мить:
Так відбувається тому, що PhpStorm знає, що в змінну $ rabbits повертається масив об'єктів класу Rabbit. Далі в циклі foreach змінна $ rabbit отримує один елемент масиву, який є екземпляром класу Rabbit і PhpStorm показує вам доступні публічні методи з цього класу.
Таким чином, не відриваючись від клавіатури, ви можете використовувати класи з публічними методами, які написали ваші колеги. PhpStorm видаватиме вам підказки, і якщо метод названий зрозуміло, ви зможете використовувати його навіть без читання його вихідного коду і документації.
Ще одна корисна фіча докблоков в парі з PhpStorm - це попередження про неправильних вхідних параметрах. Допишемо докблок для одного з методів класу Rabbit:
Тут ми вказуємо, що на вхід має приходити ціле число (знову ж таки, в PHP7 це можливо буде поставити на рівні синтаксису самої мови). Що буде, якщо ми передамо в цей метод масив?
PhpStorm виділить кольором і видасть вам підказку, що на вхід очікується int. а ви передає array. Зручно, правда? Так само підказки будуть видаватися і на невідповідність класів, інтерфейсів. Якщо ваш метод підтримує кілька типів для вхідних аргументів, то розділіть їх також через |. В даному прикладі, якщо метод runInMetres () також вміє обробляти масиви, то в докблок можна дописати «@param int | array $ metres Metres» і PhpStorm перестане лаятися.
Щоб мінімізувати дискомфорт, потрібно змусити кожного учасника команди включити в PhpStorm інспекцію докблоков Settings> Editor> Inspections> PHPDoc і відзначити там все галочки:
Так само слід використовувати PHP CodeSniffer (phpcs) з відповідним вам код стайл. Не впевнений, як щодо всіх код стайл, але для Symfony докблокі є обов'язковими. Тому phpcs в шторм видаватиме вам попередження на льоту. Налаштування робляться в тому ж місці, а ось ще є додаткова інструкція.
Звичайно це не змусить всіх на 100% дотримуватися правил. Але особливих лінивців можна навантажити ще однією цитатою з книги «Чистий код», правда, це більше ставитися до форматування коду, але зміст той самий:
«Правила повинні дотримуватися всіма учасниками групи. Це означає, що кожен учасник групи повинен бути досить розумним, щоб розуміти: неважливо, як саме розміщуються фігурні дужки, якщо тільки всі погодилися розміщувати їх однаковим чином. »
Генерація документації за допомогою phpDocumentor
Тепер, коли всі дотримуються правил, і ваш код покритий докблокамі, можна згенерувати документацію. Наводити всю документацію по phpDocumentor не буду, лише мінімум команд, решта на офіційному сайті.
Отже, потрібно встановити phpDocumentor. Його можна поставити глобально ось так:
Або додати як залежність в composer.json вашого проекту.
А тепер, перебуваючи в директорії проекту, який ви покрили докблокамі, просто запустіть з консолі:
Як я і згадував, це самий мінімальний набір дій для генерації документації, опція -d src / вказує на шлях до файлів, які ви хочете обробити. Згенерована документація буде створена в папці output. Звичайно ж, у цій утиліти є різні параметри і вона вміє різні штуки. А виглядати згенерувала документація буде так. можна вибрати існуючий шаблон або створити свій.
Генерація документації за допомогою Sami
Ще один інструмент для генерації php-документації на основі докблоков - утиліта Sami. Можливо, вона не така відома, але я вирішив її згадати, так як за допомогою Sami генерується документація нашої улюбленої Symfony. А написав цю утиліту сам Fabien Potencier, і писав про це колись у своєму блозі.
Генератор документації Sami відрізняється від phpDocumentor тим, що його конфігурація зберігається в PHP-файлах. Загалом, заточити під себе Sami можна набагато крутіше, ніж phpDocumentor, але це все доведеться робити ручками, тобто написати трохи коду. Там навіть можна перевизначати різні шматки коду, які відповідають за генерацію документації. І шаблони все на TWIG'е, зручно перевизначати. Більш детально можете познайомитися з Sami на сторінці сховища на GitHub.