Документация как инвестиция

Документация — это не скучная обязанность, а инвестиция в будущее: хорошая документация экономит время команды, снижает bus factor и делает код доступным для других.

Зачем нужно

Каждый разработчик читает чужой код — а значит, страдает от плохой документации или выигрывает от хорошей. Документация сокращает время онбординга, уменьшает количество вопросов в Slack и позволяет не держать в голове детали системы. Согласно исследованиям, разработчики тратят до 58% времени на понимание чужого кода — документация напрямую влияет на эту цифру.

Где используется

  • Кодовая база — JSDoc, inline комментарии
  • API — OpenAPI / Swagger
  • Процессы — onboarding docs, runbooks
  • Проекты — README, CONTRIBUTING, CHANGELOG

Типы документации

Code-level (в коде):
  - Комментарии: ЗАЧЕМ, а не ЧТО (что видно из кода)
  - JSDoc / TypeDoc — типы, параметры, примеры

API-level:
  - OpenAPI / Swagger — схема + примеры запросов
  - Postman Collections — живые примеры

Project-level:
  - README — что это, как запустить
  - CONTRIBUTING — как контрибьютить
  - ADR — архитектурные решения
  - Runbook — как делать повторяющиеся операции

Process-level:
  - Onboarding guide — для новых членов команды
  - Postmortem — история инцидентов
  - Decision log — почему выбрали этот подход

Принципы хорошей документации

Комментарии: зачем, а не что

// ПЛОХО — описывает что и так видно из кода:
// Увеличить счётчик на 1
counter++;

// ХОРОШО — объясняет неочевидное:
// Счётчик нечётных: начинаем с 1, т.к. 0-й элемент — заголовок
let oddCounter = 1;

// ХОРОШО — объясняет бизнес-логику:
// Скидка применяется только если заказ сделан до 23:59
// согласно правилам промо-акции (PROJ-456)
if (orderTime < dayEnd) applyDiscount;

JSDoc пример

/**
 * Форматирует цену для отображения пользователю.
 *
 * @param {number} amount - Цена в копейках
 * @param {string} currency - Код валюты (RUB, USD, EUR)
 * @returns {string} Форматированная строка: "1 234,56 ₽"
 *
 * @example
 * formatPrice(123456, 'RUB') // "1 234,56 ₽"
 * formatPrice(0, 'USD')      // "0,00 $"
 */
function formatPrice(amount, currency) { ... }

Правило "пять секунд"

Если новый человек не понимает назначение кода/модуля
за 5 секунд → нужна документация или лучшее именование

Документация Readme-Driven Development

Подход: сначала пиши README, потом код

1. Опиши, как будет использоваться API/компонент
2. Напиши примеры использования
3. Только потом реализуй

Преимущество: документация точно актуальна с первого дня

Частые ошибки

Ошибка Проблема Решение
"Код самодокументируемый" Бизнес-логика невидима из кода Комментировать намерение и контекст
Устаревшая документация Хуже чем её отсутствие — вводит в заблуждение Обновлять при изменении кода (PR-чеклист)
Документировать всё подряд Лишний шум Документировать неочевидное и публичное API
Писать документацию в последний момент Не знаешь деталей, пишешь поверхностно Документировать параллельно с кодом

Связанные темы

Ресурсы