Строгий порядок в JSDoc: @purpose → @consumer → @invariant → @pre → @param → @throws → @returns → @post → @sideEffect Для структур данных (объекты, DTO, ответы API, нормализованные модели) использовать type. interface — только для сущностей, которые наследуют или расширяют (несколько классов реализуют один контракт). Классы ошибок (extends Error) остаются class. Типы, относящиеся к внешней системе или домену (API, сервис), должны иметь префикс в имени (напр. ApiResource, ExternalServiceDto, VendorOrder). Внутренние утилитные типы без внешнего домена — без префикса. Не использовать enum. Вместо: const + as const или union type. Не использовать модификаторы в конструкторе (public, private). Явное объявление полей в теле класса. Не использовать private / #private field. Вместо: protected _field с префиксом _. readonly — в объявлении поля, не в параметре конструктора. Телеологическое назначение. Зачем эта сущность существует в бизнес-логике? ВСЕГДА для любых экспортируемых (export) сущностей (классы, методы, типы, интерфейсы, константы). @purpose {Глагол} {Объект} {Контекст}. Кто является клиентом этого API? (Другие модули, UI, внешние системы). Для корневых сущностей (классы, модули) и публичных методов API. Для внутренних утилитных типов или методов. @consumer {ModuleName}, {SystemName} Описание входящего аргумента: одно связное описание бизнес-роли и границ валидности. Для параметров-объектов описывается их общая роль, без дублирования описания внутренних полей. ВСЕГДА, если у функции есть аргументы. Если функция не принимает аргументов. @param {name} {Одно связное описание: что это и допустимые границы}. @param [{name}] {Одно связное описание}. Бизнес-цель результата: зачем вызывающему нужен результат. Для асинхронных функций описывает значение, которым успешно разрешается Promise. ВСЕГДА, если функция возвращает значение (не void/never). Если функция возвращает void. @returns {Цель результата для вызывающего}. Предпословие. Состояние системы или окружения (не связанное с простой валидацией аргументов), которое ДОЛЖНО быть истинным ДО вызова. Если есть скрытые требования к окружению или состоянию системы, не дублирующие @param. Если дублирует @param или требования только из типов TypeScript. @pre {Состояние системы/окружения}. Постусловие. Гарантированное состояние системы ПОСЛЕ успешного выполнения. Если метод меняет стейт или даёт гарантию, не выраженную в @returns (напр. неизменность аргумента, порядок элементов). Если дублирует @returns или @param; для чистых функций без дополнительных гарантий. @post {Факт об изменении состояния или гарантия}. Условие, которое всегда остается истинным для жизни сущности. Для внешних сервисов описывает SLA, политику обработки ошибок (Error Policy) и стратегию повторных запросов (Retry Policy). Для Классов/Интерфейсов с состоянием или клиентов внешних систем. Для функций-утилит (stateless). @invariant {Условие целостности или Политика}. Любое взаимодействие с внешним миром (IO, Network, Logs, Events , etc). ВСЕГДА, если метод не является чистой функцией. Если метод только вычисляет и возвращает данные. @sideEffect {Тип действия}: {Описание}. Описание исключительной ситуации. Для асинхронных функций описывает причину отклонения (reject) Promise. Если метод может выбросить ошибку (throw) или вернуть Rejected Promise. Если метод гарантированно безопасен (never throws). @throws {ErrorType | RejectedPromiseReason} {Условие возникновения}. Ссылка на определение контракта (Interface/Spec/Type), который реализует этот код. При реализации интерфейса или наследовании, чтобы не дублировать описание. Если это первичное определение контракта. @see {TypeName#method} in path/from/project/root Пример использования кода. Если логика вызова неочевидна или требует сложной подготовки данных. Для тривиальных методов (get/set). @example {Code block} Маркер устаревшего кода. Если метод планируется к удалению. Обязательно указать альтернативу. Для актуального кода. @deprecated Используй {NewMethod} вместо этого. Определение типа данных (type) или контракта данных (interface). Данные: type с @purpose; при принадлежности к домену/API — префикс в имени. Логика: pre/post только если не дублируют param/returns. /** * @purpose Описывает элемент каталога внешнего сервиса — идентификатор и дочерние элементы. * @consumer catalog-service, export-module. */ export type ApiCatalogItem = { id: string; children: ApiCatalogItem[]; }; Интерфейс или Клиент к внешней системе (API, DB, IO). Ненадежная среда. Обязательно: 1. Иерархия ошибок (Base → Network/Auth/Domain). 2. @invariant с описанием Resilience Policy (Retry, Rate Limits, Timeout). /** * @purpose Клиент для работы с платежным шлюзом. * @consumer billing-service * @invariant Error Policy: Все сетевые ошибки оборачиваются в PaymentNetworkError. * @invariant Retry Policy: Идемпотентные методы (GET) повторяются 3 раза с экспоненциальной задержкой. * @invariant Rate Limit: Не более 100 rps (контролируется клиентом). */ export interface PaymentGateway { ... } Реализация сущности, которая уже описана во внешнем контракте (implements Interface). Не дублируй логику. Используй @purpose (кратко), @consumer и @see. /** * @purpose Реализация трансформации для мобильных устройств. * @consumer MobileApp * @see {UserTransformer} in features/users/contracts.ts */ export const mobileUserTransformer: UserTransformer = (u) => { ... }; Метод класса. Если реализует интерфейс — @see. Иначе — полный контракт. /** * @purpose Списание средств. * @pre Система должна быть в режиме read-write (не maintenance). * @param amount Сумма к списанию (положительное число). * @throws {NoFundsError} Если баланс недостаточен. */ public pay(amount: number): void { ... } Стандартная функция. @param не дублирует поля типа. Публичные константы, особенно объекты конфигурации. Опиши @purpose (зачем этот конфиг) и @invariant (ограничения значений). /** * @purpose Глобальные настройки ретраев для HTTP. * @invariant maxRetries должно быть меньше 5. */ export const RETRY_CONFIG = { ... }; Асинхронная функция, возвращающая Promise. @returns описывает значение при успешном resolve. @throws описывает причину (Error) при reject. /** * @purpose Загружает данные пользователя с сервера. * @param userId ID пользователя для загрузки (UUIDv4). * @throws {UserNotFoundError} Если пользователь с таким ID не найден. * @returns {Promise} Данные пользователя для внутреннего использования в системе. * @sideEffect Network: GET-запрос к /api/users/{userId} */ export async function fetchUser(userId: string): Promise { ... } Обобщенная (generic) функция с параметризованными типами. В @param и @returns следует описать роль обобщенного типа T. /** * @purpose Оборачивает любые входные данные в стандартизированный объект ответа. * @param data Данные любого типа {T}, которые будут помещены в поле `payload`. * @returns {ApiResponse} Стандартизированный объект ответа, содержащий исходные данные. */ export function wrapInApiResponse(data: T): ApiResponse { ... } Экспортируемая сущность: есть @purpose; для корневых типов и публичного API — @consumer при необходимости. Класс/модуль с состоянием: есть @invariant. Внешний сервис (Client/Interface): определен @invariant с иерархией ошибок и Retry Policy. @param — одно связное описание. Для объектов описание полей не дублируется из типа. @returns — бизнес-цель результата для вызывающего, а не перечисление типа. Порядок тегов соблюдён: purpose → consumer → invariant → pre → param → throws → returns → post → sideEffect. @pre и @post не дублируют @param/@returns; только если добавляют новую информацию. Метод с побочными эффектами: есть @post или @sideEffect. Реализация внешнего типа: есть @see с путем от корня. Структуры данных объявлены через type; interface только при наследовании/реализации. Типы внешнего домена/API имеют префикс в имени. Асинхронность: @returns описывает успех, @throws — ошибку (reject).