70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
---
|
||
title: Документирование
|
||
---
|
||
|
||
# Документирование
|
||
|
||
## Правило для документирования кода
|
||
|
||
- Документировать разрешено только описание (назначение) функций, компонентов, типов, интерфейсов, enum и их полей.
|
||
- Строго запрещено документировать параметры, возвращаемые значения, типы пропсов, аргументы, возвращаемые значения функций, компоненты, хуки и т.д.
|
||
- В интерфейсах, типах и enum разрешено документировать только смысл (описание) каждого поля или значения.
|
||
- В React-компонентах, функциях, хранилищах, схемах, утилитах разрешено документировать только назначение (описание), без детализации параметров и возвращаемых значений.
|
||
- Описание должно быть кратким, информативным и реально помогать понять структуру и бизнес-логику.
|
||
- Не допускается избыточная или дублирующая очевидное документация.
|
||
- В конце описания всегда ставить точку.
|
||
|
||
**Примеры правильного документирования**
|
||
```tsx
|
||
/**
|
||
* Список задач пользователя.
|
||
*/
|
||
export const TodoList = memo(() => { ... });
|
||
|
||
/**
|
||
* Интерфейс задачи.
|
||
*/
|
||
export interface TodoItem {
|
||
/** Уникальный идентификатор задачи. */
|
||
id: string;
|
||
/** Текст задачи. */
|
||
text: string;
|
||
/** Статус выполнения задачи. */
|
||
completed: boolean;
|
||
}
|
||
|
||
/**
|
||
* Перечисление фильтров задач.
|
||
*/
|
||
export enum TodoFilter {
|
||
/** Все задачи. */
|
||
All = 'all',
|
||
/** Только активные задачи. */
|
||
Active = 'active',
|
||
/** Только выполненные задачи. */
|
||
Completed = 'completed',
|
||
}
|
||
```
|
||
|
||
**Примеры неправильного документирования**
|
||
```ts
|
||
// ❌ Не нужно:/
|
||
/**
|
||
* @param id - идентификатор задачи
|
||
* @returns объект задачи
|
||
*/
|
||
|
||
// ❌ Не нужно:/
|
||
/**
|
||
* @param props - пропсы компонента
|
||
* @returns JSX.Element
|
||
*/
|
||
|
||
// ❌ Не нужно:/
|
||
/**
|
||
* id — идентификатор задачи
|
||
* text — текст задачи
|
||
* completed — статус выполнения
|
||
*/
|
||
```
|