Ответ
Я веду документацию непосредственно в репозитории проекта, чтобы она версионировалась вместе с кодом. Основные форматы и места:
1. Markdown-файлы в корне и папках проекта:
README.md— визитная карточка: описание проекта, быстрый старт, основные зависимости.CONTRIBUTING.md— руководство для контрибьюторов.CHANGELOG.md— история изменений в формате Keep a Changelog.- Папка
/docsдля подробной документации:setup.md,api.md,deployment.md.
2. Инлайн-документирование кода (PHPDoc/JavaDoc):
/**
* Рассчитывает итоговую цену заказа с учетом скидки и налогов.
*
* @param array<OrderItem> $items Массив товаров в заказе.
* @param float $discountRate Процент скидки (от 0 до 1).
* @param string $taxRegion Регион для расчета налога.
* @return float Итоговая цена.
* @throws InvalidArgumentException Если процент скидки некорректен.
* @throws TaxCalculationException Если расчет налога для региона невозможен.
*/
public function calculateTotalPrice(array $items, float $discountRate, string $taxRegion): float
{
// ... реализация
}3. Документирование API:
Для REST API использую OpenAPI (Swagger). Спецификация в формате YAML/JSON (openapi.yaml) позволяет автоматически генерировать интерактивную документацию (Swagger UI) и клиентские SDK.
4. Архитектурные решения:
Важные архитектурные решения фиксирую в формате ADR (Architecture Decision Record) в папке docs/adr/. Это помогает команде понимать контекст принятых решений.
Такой подход обеспечивает актуальность документации, так как ее изменение становится частью code review в пул-реквесте.
Ответ 18+ 🔞
Давай разберём, как я обычно пилю документацию, чтобы потом самому не охуеть через полгода. Ты ж знаешь, как бывает: открываешь свой же проект, а там нихуя не понятно, как его запустить и что эта функция делает. Волнение ебать, терпения ноль ебать. Поэтому я всё храню прямо в репо, чтобы оно версионировалось вместе с кодом и не терялось.
1. Маркдаун-файлы, они же наши спасательные круги.
README.md— это, блядь, лицо проекта. Сюда пишу, что это за зверь такой, как его быстро запустить (чтобы не тратить полдня) и какие зависимости ему скормить. Если этого нет, то проект — манда с ушами.CONTRIBUTING.md— инструкция для тех, кто хочет помочь. Чтобы не присылали кривые пул-реквесты, где табы с пробелами перемешаны.CHANGELOG.md— летопись всех наших подвигов и косяков. Ведём по правилам Keep a Changelog, чтобы было понятно, что сломалось в новой версии.- Папка
/docs— тут уже подробные мануалы: как настроить (setup.md), как работать с API (api.md), как выкатить на продакшн (deployment.md). Без этого — чих-пых тебя в сраку, когда нужно что-то вспомнить.
2. Комментарии прямо в коде (PHPDoc/JavaDoc). Вот смотри, чтобы не гадать, что делает функция, я её обкладываю комментами, как пряниками. Это же элементарно, ёпта!
/**
* Считает, сколько с тебя сдерут денег за заказ, учитывая все твои скидочки и налоги.
*
* @param array<OrderItem> $items Что ты там набрал в корзину.
* @param float $discountRate Твоя скидка (от 0 до 1, где 1 — это 'отдай всё даром').
* @param string $taxRegion Регион, где ты живёшь. От этого зависит, сколько государство отщипнёт.
* @return float Итоговая сумма, которую ты заплатишь. Приготовь кошелёк.
* @throws InvalidArgumentException Если скидка кривая (например, 250%).
* @throws TaxCalculationException Если твой регион настолько дикий, что налоги для него не посчитать.
*/
public function calculateTotalPrice(array $items, float $discountRate, string $taxRegion): float
{
// ... а вот тут уже магия происходит
}3. Для API — только OpenAPI (Swagger).
Если делаю REST API, то пишу спецификацию в openapi.yaml. Это, блядь, золотой стандарт. Из этого файла автоматом генерируется красивая, интерактивная документация (Swagger UI), где можно тыкать в эндпоинты. И заодно можно нагенерить SDK для кучи языков. Красота, а не жизнь.
4. Про архитектурные решения.
Бывает, принимаешь какое-то важное решение — например, почему взял именно эту БД, а не ту. Через месяц все забывают, а через год приходит новый чувак и спрашивает: «А какого хуя?». Чтобы не выглядеть идиотом, я записываю это в ADR (Architecture Decision Record) и кладу в docs/adr/. Теперь есть контекст, и все довольны.
Весь этот подход хорош тем, что когда ты меняешь код и поправляешь доку — это всё идёт одним коммитом и одним пул-реквестом. На ревью смотрят и код, и описание к нему. Так что шансов, что документация уедет в лес и будет описывать прошлую версию, — почти ноль. А если и будет, то виноват будет конкретный распиздяй, а не злой рок.