frontend-style-guide/OLD_parts/7-docs.md

title

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

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

Правило для документирования кода

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

Примеры правильного документирования

/**
 * Список задач пользователя.
 */
export const TodoList = memo(() => { ... });

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

/**
 * Перечисление фильтров задач.
 */
export enum TodoFilter {
  /** Все задачи. */
  All = 'all',
  /** Только активные задачи. */
  Active = 'active',
  /** Только выполненные задачи. */
  Completed = 'completed',
}

Примеры неправильного документирования

// ❌ Не нужно:/
/**
 * @param id - идентификатор задачи
 * @returns объект задачи
 */

// ❌ Не нужно:/
/**
 * @param props - пропсы компонента
 * @returns JSX.Element
 */

// ❌ Не нужно:/
/**
 * id — идентификатор задачи
 * text — текст задачи
 * completed — статус выполнения
 */