Документация в JavaScript: как писать код, который говорит сам за себя

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Почему документация — это не скучная обязанность, а суперсила разработчика

Представьте: вы открываете чужой (или свой собственный трёхмесячной давности) JavaScript-проект. Файлы пестрят стрелочными функциями, async/await и деструктуризацией. Но почему эта функция называется transformData? Что она принимает? И главное — зачем она нужна, если рядом есть processArray?

Если вы хоть раз ловили себя на мысли: «Я не помню, что здесь происходит», — эта статья для вас. Документация в JavaScript — это не про скучные абзацы текста. Это про уважение к будущему себе и коллегам. Это про скорость входа в проект и снижение количества багов. В этой статье мы разберём лучшие практики документирования JS-кода: от JSDoc до генерации полноценной документации.

Документация кода JavaScript: философия «говорящего кода»

Прежде чем писать комментарии, важно понять: лучший комментарий — тот, который не нужен. Идеальный код должен объяснять себя сам. Как этого добиться?

Именование переменных и функций

Плохой пример:

// Плохо
const x = 10; // что такое x?
function d(a, b) { return a * b; } // что делает d?

Хороший пример:

// Хорошо
const MAX_RETRY_COUNT = 10;
function calculateDiscountedPrice(price, discountPercent) {
  return price * (1 - discountPercent / 100);
}

Используйте полные, осмысленные имена. Функции называйте глаголами (getUser, validateEmail), переменные — существительными (userList, isActive). Это основа самодокументируемого кода.

Когда комментарии всё-таки нужны

Сложная бизнес-логика: например, расчёт налогов по неочевидной формуле.
Хак или временное решение: пометьте TODO или FIXME.
Почему выбран именно такой подход: альтернативы были, но эта — оптимальная по скорости.
Описание публичного API: чтобы другие разработчики знали, как вызвать вашу функцию.

JSDoc: стандарт документирования JavaScript

JSDoc — это синтаксис для написания документации прямо в коде, который понимают редакторы (VS Code, WebStorm) и инструменты генерации. Это must-have для любого серьёзного проекта.

Базовая аннотация функции

/**
 * Рассчитывает итоговую стоимость заказа с учётом скидки и налога.
 * @param {number} price - Базовая цена товара.
 * @param {number} discount - Скидка в процентах (0-100).
 * @param {number} taxRate - Ставка налога в процентах (0-100).
 * @returns {number} Итоговая стоимость.
 */
function calculateTotal(price, discount, taxRate) {
  const discountedPrice = price * (1 - discount / 100);
  return discountedPrice * (1 + taxRate / 100);
}

Теперь при наведении на функцию calculateTotal в редакторе вы увидите её описание, параметры и возвращаемое значение. Магия!

Аннотации для объектов и типов

/**
 * @typedef {Object} User
 * @property {number} id - Уникальный идентификатор.
 * @property {string} name - Имя пользователя.
 * @property {boolean} isActive - Активен ли аккаунт.
 */

/**
 * Получает список активных пользователей.
 * @param {User[]} users - Массив пользователей.
 * @returns {User[]} Отфильтрованный массив.
 */
function getActiveUsers(users) {
  return users.filter(user => user.isActive);
}

Использование @typedef позволяет создавать собственные типы, что делает код читаемым и безопасным. Это особенно полезно в проектах без TypeScript.

Документирование асинхронных функций

/**
 * Загружает данные пользователя с сервера.
 * @async
 * @param {number} userId - ID пользователя.
 * @returns {Promise<User>} Объект пользователя.
 * @throws {Error} Если пользователь не найден.
 */
async function fetchUser(userId) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) throw new Error('User not found');
  return response.json();
}

Не забывайте указывать @async и тип возвращаемого Promise.

Генерация документации: от JSDoc к красивой HTML-странице

Написать аннотации — полдела. Второе — превратить их в удобную документацию. Самый популярный инструмент — JSDoc (да, утилита называется так же).

Как сгенерировать документацию

Установите глобально: npm install -g jsdoc
Запустите в корне проекта: jsdoc src/ -d docs
Откройте docs/index.html — готовая документация!

Для более продвинутого использования настройте conf.json для подключения плагинов и шаблонов.

Альтернативы JSDoc

TypeScript: если вы готовы перейти на TS, документация генерируется автоматически через TypeDoc.
ESDoc: более современный инструмент с поддержкой ES6 модулей и красивыми темами.
Documentation.js: лёгкий и быстрый, поддерживает JSDoc-аннотации.

Лучшие практики документирования JavaScript кода

Теперь, когда мы знаем инструменты, давайте соберём правила хорошего тона.

1. Документируйте публичный API, а не внутренности

Не нужно писать JSDoc для каждой приватной переменной. Сосредоточьтесь на функциях, методах классов и модулях, которые используются в других частях проекта. Внутренние хелперы могут быть понятны из названия.

2. Используйте @example для иллюстрации

/**
 * Форматирует дату в читаемый вид.
 * @param {Date} date - Объект даты.
 * @returns {string} Строка вида "12 марта 2025 г.".
 * @example
 * // returns "1 января 2024 г."
 * formatDate(new Date(2024, 0, 1));
 */
function formatDate(date) {
  // ...
}

Примеры кода — лучший способ показать, как работает функция. В сгенерированной документации они будут выделены отдельно.