Документирование

Правила документирования кода: что и когда документировать через JSDoc.

Общие правила

• Документировать публичные функции, компоненты, типы, интерфейсы и enum.
• Не документировать очевидное — если название говорит само за себя, комментарий не нужен.
• Не документировать параметры, возвращаемые значения и типы пропсов — они видны из сигнатуры.
• Описание через пользу и назначение, а не через внутреннюю реализацию.
• Описание завершается точкой.

Функции

Для документирования функций используется шаблон. Описание механики опционально — добавляется когда логика нетривиальна.

Шаблон

/**
 * <Что делает функция в 1 строке>.
 *
 * <Опционально: описание сложной механики или важных нюансов>.
 */

Хорошо

/**
 * Форматирует цену с символом валюты.
 */
export const formatPrice = (value: number): string => { ... }

/**
 * Рекурсивно собирает дерево категорий из плоского списка.
 *
 * Группирует элементы по parentId, начиная с корневых (parentId = null).
 * Категории без родителя попадают в корень дерева.
 */
export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { ... }

Плохо

// Плохо: дублирует сигнатуру.
/**
 * @param value - число
 * @returns строка с ценой
 */

Компоненты

Компонент описывает своё назначение и сценарии применения — это помогает понять, когда и где его использовать, без необходимости читать реализацию.

Шаблон

/**
 * <Назначение компонента в 1 строке>.
 *
 * Используется для:
 *  - <сценарий 1>
 *  - <сценарий 2>
 *  - <сценарий 3>
 */

Хорошо

/**
 * Контейнер с адаптивной максимальной шириной.
 *
 * Используется для:
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
export const Container = (props: ContainerProps) => { ... }

Плохо

// Плохо: описывает реализацию, а не назначение.
/**
 * Рендерит div с className и htmlAttr.
 */

// Плохо: нет описания вообще.
export const Container = (props: ContainerProps) => { ... }

Типы, интерфейсы, enum

Документируются назначение сущности и каждое её поле.

Хорошо

/**
 * Фильтры списка задач.
 */
export enum TodoFilter {
  /** Все задачи. */
  ALL = 'all',
  /** Только активные. */
  ACTIVE = 'active',
  /** Только завершённые. */
  COMPLETED = 'completed',
}

/**
 * Задача пользователя.
 */
export interface TodoItem {
  /** Уникальный идентификатор задачи. */
  id: string;
  /** Текст задачи. */
  text: string;
  /** Статус выполнения. */
  completed: boolean;
}

Плохо

// Плохо: описывает очевидное.
export interface TodoItem {
  /** id — это id */
  id: string;
}