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 — статус выполнения
|
|||
|
|
*/
|
|||
|
|
```
|