sync
This commit is contained in:
@@ -6,29 +6,9 @@ title: Стиль кода
|
||||
|
||||
Раздел описывает единые правила оформления кода: отступы, переносы, кавычки, порядок импортов и базовую читаемость.
|
||||
|
||||
## Отступы и переносы
|
||||
## Отступы
|
||||
|
||||
- Использовать 2 пробела для отступов.
|
||||
- Не использовать табы.
|
||||
- Одна инструкция — одна строка.
|
||||
- Между логическими блоками оставлять пустую строку по необходимости, если это улучшает читаемость.
|
||||
- В многострочных конструкциях выравнивать закрывающую скобку по началу выражения.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const payload = {
|
||||
id: 1,
|
||||
name: 'User',
|
||||
meta: {
|
||||
role: 'admin',
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
const payload = { id: 1, name: 'User', meta: { role: 'admin' } };
|
||||
```
|
||||
- 2 пробела (не табы).
|
||||
|
||||
## Длина строк
|
||||
|
||||
@@ -57,6 +37,7 @@ const config = createRequestConfig(
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: длинная строка с вложенными структурами плохо читается.
|
||||
const config = createRequestConfig(endpoint, { headers: { 'X-Request-Id': requestId, 'X-User-Id': userId }, params: { page, pageSize, sort: 'createdAt' } }, timeoutMs);
|
||||
```
|
||||
|
||||
@@ -78,11 +59,13 @@ const title = `Привет, ${name}`;
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: двойные кавычки в TS и конкатенация вместо шаблонной строки.
|
||||
const label = "Сохранить";
|
||||
const title = 'Привет, ' + name;
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Плохо: одинарные кавычки в JSX-атрибутах.
|
||||
<input type='text' placeholder='Введите имя' />
|
||||
```
|
||||
|
||||
@@ -106,6 +89,7 @@ import type { User } from '../model/types';
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: default импорт и отсутствие пробелов в именованном импорте.
|
||||
import MyComponent from 'MyComponent';
|
||||
import type {User} from '../model/types';
|
||||
```
|
||||
@@ -128,6 +112,7 @@ const getName = (user?: { name: string }) => {
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: лишний else после return усложняет чтение.
|
||||
const getName = (user?: { name: string }) => {
|
||||
if (user) {
|
||||
return user.name;
|
||||
@@ -146,7 +131,7 @@ const getName = (user?: { name: string }) => {
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const roles = ['admin', 'editor'];
|
||||
const roles = ['admin', 'editor', 'viewer'];
|
||||
const options = { id: 1, name: 'User' };
|
||||
|
||||
const config = {
|
||||
@@ -158,7 +143,8 @@ const config = {
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
const roles = ['admin','editor'];
|
||||
// Плохо: нет пробелов после запятых и объект слишком длинный для одной строки.
|
||||
const roles = ['admin','editor','viewer'];
|
||||
const options = { id: 1,name: 'User' };
|
||||
const config = { url: '/api/users', method: 'GET', params: { page: 1, pageSize: 20 } };
|
||||
```
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Именование
|
||||
---
|
||||
|
||||
# Именование
|
||||
|
||||
Именование должно быть предсказуемым, коротким и отражать смысл сущности.
|
||||
|
||||
## Базовые правила
|
||||
|
||||
| Что | Рекомендуется |
|
||||
| ---------------- | ---------------------- |
|
||||
| Папки | `kebab-case` |
|
||||
| Файлы | `kebab-case` |
|
||||
| Переменные | `camelCase` |
|
||||
| Константы | `SCREAMING_SNAKE_CASE` |
|
||||
| Классы | `PascalCase` |
|
||||
| React-компоненты | `PascalCase` |
|
||||
| Хуки | `useSomething` |
|
||||
| CSS классы | `camelCase` |
|
||||
|
||||
|
||||
## Архитектурный неймспейс
|
||||
|
||||
Соглашение о суффиксах, которые обозначают слой (уровень абстракции), роль или тип файла.
|
||||
|
||||
- Суффиксы используются для обозначения слоя, роли или типа файла.
|
||||
- Суффиксы всегда пишутся в единственном числе.
|
||||
- Формат имени: `name.<suffix>.ts` или `name.<suffix>.tsx`.
|
||||
|
||||
**UI и слои FSD**
|
||||
- `.screen.tsx` — экран
|
||||
- `.layout.tsx` — layout
|
||||
- `.widget.tsx` — виджет
|
||||
- `.feature.tsx` — UI фичи
|
||||
- `.entity.tsx` — UI сущности
|
||||
- `.ui.tsx` — UI‑компонент
|
||||
|
||||
**Логика и модель**
|
||||
- `.store.ts` — стор
|
||||
- `.service.ts` — сервис
|
||||
|
||||
**Типы и контракты**
|
||||
- `.type.ts` — типы и интерфейсы
|
||||
- `.interface.ts` — файл с интерфейсами (если нужен отдельный контракт)
|
||||
- `.enum.ts` — enum
|
||||
- `.dto.ts` — внешние DTO
|
||||
- `.schema.ts` — схемы валидации
|
||||
- `.constant.ts` — константы
|
||||
- `.config.ts` — конфигурация
|
||||
|
||||
**Утилиты и хелперы**
|
||||
- `.util.ts` — утилиты
|
||||
- `.helper.ts` — вспомогательные функции
|
||||
- `.lib.ts` — вспомогательные функции
|
||||
|
||||
**Тесты**
|
||||
- `.test.ts` / `.test.tsx`
|
||||
- `.mock.ts`
|
||||
|
||||
|
||||
**Хорошо**
|
||||
```text
|
||||
src/
|
||||
├── screens/
|
||||
│ └── main/
|
||||
│ ├── main.screen.tsx
|
||||
│ └── index.ts
|
||||
├── features/
|
||||
│ └── auth-by-email/
|
||||
│ ├── ui/
|
||||
│ │ └── login-form.ui.tsx
|
||||
│ ├── auth-by-email.feature.tsx
|
||||
│ └── index.ts
|
||||
└── shared/
|
||||
└── ui/
|
||||
└── icon/
|
||||
├── icon.ui.tsx
|
||||
└── icon.module.css
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```text
|
||||
// Плохо: нет единых правил для слоёв и публичных файлов.
|
||||
src/
|
||||
├── screens/
|
||||
│ └── Main/
|
||||
│ └── Main.tsx
|
||||
└── features/
|
||||
└── authByEmail/
|
||||
└── login-form.tsx
|
||||
```
|
||||
|
||||
## Булевы значения
|
||||
|
||||
- Использовать префиксы `is`, `has`, `can`, `should`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const isReady = true;
|
||||
const hasAccess = false;
|
||||
const canSubmit = true;
|
||||
const shouldRedirect = false;
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: неясное булево значение без префикса.
|
||||
const ready = true;
|
||||
const access = false;
|
||||
const submit = true;
|
||||
```
|
||||
|
||||
## События и обработчики
|
||||
|
||||
- Обработчики начинать с `handle`.
|
||||
- События и колбэки начинать с `on`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const handleSubmit = () => { ... };
|
||||
const onSubmit = () => { ... };
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: неочевидное назначение имени.
|
||||
const submitClick = () => { ... };
|
||||
```
|
||||
|
||||
## Коллекции
|
||||
|
||||
- Для массивов использовать имена во множественном числе.
|
||||
- Для словарей/мап — использовать суффиксы `ById`, `Map`, `Dict`.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const users = [];
|
||||
const usersById = {} as Record<string, User>;
|
||||
const userIds = ['u1', 'u2'];
|
||||
const ordersMap = new Map<string, Order>();
|
||||
const featureFlagsDict = { beta: true, legacy: false } as Record<string, boolean>;
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: имя не отражает, что это коллекция.
|
||||
const user = [];
|
||||
// Плохо: словарь назван как массив.
|
||||
const usersMap = [];
|
||||
// Плохо: по имени непонятно, что это словарь.
|
||||
const users = {} as Record<string, User>;
|
||||
```
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Документирование
|
||||
---
|
||||
|
||||
# Документирование
|
||||
|
||||
Документирование должно помогать понять назначение сущности, а не дублировать её типы или очевидные детали.
|
||||
|
||||
## Правила
|
||||
|
||||
- Документировать только назначение функций, компонентов, типов, интерфейсов и enum.
|
||||
- Не документировать параметры, возвращаемые значения, типы пропсов и очевидные детали.
|
||||
- В интерфейсах, типах и enum описывать только смысл поля или значения.
|
||||
- Описание должно быть кратким, информативным и завершаться точкой.
|
||||
|
||||
## Примеры
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
/**
|
||||
* Список задач пользователя.
|
||||
*/
|
||||
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 объект задачи
|
||||
*/
|
||||
|
||||
// Плохо: описание очевидных деталей.
|
||||
/**
|
||||
* id — идентификатор задачи
|
||||
* text — текст задачи
|
||||
* completed — статус выполнения
|
||||
*/
|
||||
```
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Типизация
|
||||
---
|
||||
|
||||
# Типизация
|
||||
|
||||
Типизация обязательна для всех публичных интерфейсов, функций и компонентов.
|
||||
Цель — предсказуемость, безопасность и автодополнение.
|
||||
|
||||
## Общие правила
|
||||
|
||||
- Указывать типы для параметров компонентов, возвращаемых значений и параметров функций.
|
||||
- Предпочитать `type` для описания сущностей и `interface` для расширяемых контрактов.
|
||||
- Избегать `any` и `unknown` без необходимости.
|
||||
- Не использовать `ts-ignore`, кроме крайних случаев с явным комментарием причины.
|
||||
|
||||
## Типы для компонентов
|
||||
|
||||
- Типизировать параметры и публичный интерфейс компонента.
|
||||
- Дефолтные значения описывать явно в коде.
|
||||
|
||||
**Хорошо**
|
||||
```tsx
|
||||
/**
|
||||
* Параметры кнопки.
|
||||
*/
|
||||
interface IOwnProps extends HTMLAttributes<HTMLDivElement> {
|
||||
/** Текст кнопки. */
|
||||
label: string;
|
||||
/** Обработчик клика по кнопке. */
|
||||
onClick: () => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Кнопка с пользовательскими стилями.
|
||||
*/
|
||||
export const Button:FC<IOwnProps> = ({ className, label, onClick, ...htmlAttr }) => {
|
||||
return (
|
||||
<div {...htmlAttr} className={cl(styles.root, className)}>
|
||||
button
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```tsx
|
||||
// Плохо: параметры не типизированы.
|
||||
export const Button = (props) => (
|
||||
<button type="button" onClick={props.onClick}>
|
||||
{props.label}
|
||||
</button>
|
||||
);
|
||||
```
|
||||
|
||||
## Функции
|
||||
|
||||
- Для публичных функций указывать возвращаемый тип.
|
||||
- Не полагаться на неявный вывод для важных API.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
export const formatPrice = (value: number): string => {
|
||||
return `${value} ₽`;
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: нет явного возвращаемого типа.
|
||||
export const formatPrice = (value: number) => {
|
||||
return `${value} ₽`;
|
||||
};
|
||||
```
|
||||
|
||||
## Работа с any/unknown
|
||||
|
||||
- `any` использовать только для временных заглушек.
|
||||
- `unknown` сужать через проверки перед использованием.
|
||||
|
||||
**Хорошо**
|
||||
```ts
|
||||
const parse = (value: unknown): string => {
|
||||
if (typeof value === 'string') {
|
||||
return value;
|
||||
}
|
||||
|
||||
return '';
|
||||
};
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```ts
|
||||
// Плохо: any отключает проверку типов.
|
||||
const parse = (value: any) => value;
|
||||
```
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Структура проекта
|
||||
---
|
||||
|
||||
# Структура проекта
|
||||
|
||||
Раздел описывает базовую структуру проекта и принципы организации модулей на уровне папок и файлов.
|
||||
|
||||
## Базовая структура проекта
|
||||
|
||||
**Хорошо**
|
||||
```text
|
||||
src/
|
||||
├── app/ # Инициализация приложения, роутинг, провайдеры
|
||||
│ ├── config/ # Конфигурации и константы уровня приложения
|
||||
│ ├── providers/ # Провайдеры и обёртки приложения
|
||||
│ ├── routing/ # Конфигурация маршрутов
|
||||
│ └── index.ts # Публичный API слоя
|
||||
├── screens/ # Экраны приложения
|
||||
│ └── Profile/ # Экран профиля
|
||||
│ └── ... # ui/model/index.ts
|
||||
├── layouts/ # Общие шаблоны и каркасы страниц
|
||||
│ └── MainLayout/ # Основной layout
|
||||
│ └── ... # ui/index.ts
|
||||
├── widgets/ # Крупные блоки интерфейса
|
||||
│ └── Header/ # Виджет шапки
|
||||
│ └── ... # ui/index.ts
|
||||
├── features/ # Пользовательские сценарии
|
||||
│ └── auth-by-email/ # Авторизация по email
|
||||
│ └── ... # ui/model/api/index.ts
|
||||
├── entities/ # Бизнес-сущности
|
||||
│ └── user/ # Сущность пользователя
|
||||
│ └── ... # ui/model/api/lib/index.ts
|
||||
└── shared/ # Общие ресурсы проекта
|
||||
├── ui/ # Базовые UI-компоненты
|
||||
├── lib/ # Утилиты и хелперы
|
||||
├── services/ # Общие сервисы и клиенты
|
||||
├── config/ # Общие конфигурации
|
||||
├── styles/ # Глобальные стили и токены
|
||||
└── assets/ # Ресурсы
|
||||
├── images/ # Изображения
|
||||
├── icons/ # Иконки
|
||||
├── fonts/ # Шрифты
|
||||
└── video/ # Видео
|
||||
```
|
||||
|
||||
**Плохо**
|
||||
```text
|
||||
// Плохо: слои смешаны, нет понятных границ и публичного API.
|
||||
src/
|
||||
├── components/
|
||||
├── api/
|
||||
├── styles/
|
||||
└── user.ts
|
||||
```
|
||||
|
||||
## Правила организации
|
||||
|
||||
- Каждый слой и модуль хранится в собственной папке.
|
||||
- Внутренние реализации разделяются на `ui`, `model`, `lib`, `api`.
|
||||
- Публичный API модуля объявляется в `index.ts`.
|
||||
- Внутренние файлы не импортируются напрямую извне.
|
||||
- Не смешивать ответственность разных слоёв в одном модуле.
|
||||
|
||||
Reference in New Issue
Block a user