# Contributing to fock-logger

Спасибо за интерес к проекту! Мы приветствуем любые вклады: исправления ошибок, улучшения документации, новые возможности.

Прежде чем отправить pull request, пожалуйста, ознакомьтесь с правилами ниже.

## Соглашение о код-стайле (LAF)

Проект строго следует **Соглашению о код-стайле LAF** (Lazy & Focused).  
Полный текст соглашения доступен по ссылке: [https://docs.laf-team.ru](https://docs.laf-team.ru/agreements/general)

Краткое изложение основных обязательных правил:

### 1. Наименование

- Используйте **camelCase** для переменных, функций, полей, параметров.
- **UpperCamelCase** для классов, интерфейсов, типов, перечислений.
- **SCREAMING_SNAKE_CASE** для констант (кроме локальных констант в функциях, где допустим camelCase).
- Имена должны быть осмысленными, отражать суть, без артиклей и транслита.
- Избегайте сокращений, за исключением общепринятых (см. полный список в соглашении LAF).
- Для булевых переменных используйте прилагательные в прошедшем времени или префикс `is` (например, `isActive`, `enabled`).

### 2. Функции и методы

- Функция должна выполнять **одно действие** (Single Responsibility).
- Принимать **не более трёх аргументов**. Если нужно больше – объединяйте их в объект.
- Длина функции – не более 100 строк (оптимально 20–30 строк).
- Не изменять переданные параметры (иммутабельность).
- Название должно содержать глагол (например, `getUser`, `validateInput`).
- Для булевых возвращаемых значений используйте вопрос: `isActive`, `hasAccess`.
- Для обработчиков событий – префикс `on`: `onClick`, `onData`.
- Избегайте возврата `null` или `undefined`, если это не предусмотрено логикой; лучше бросать ошибку или возвращать `false`.

### 3. Классы

- Имена классов – существительные.
- Поля по умолчанию должны быть `private`. Используйте `protected` только для наследования, `public` – только для API.
- Инициализация всех полей должна происходить в конструкторе.
- Единый стиль для основного метода: **`execute`** (по умолчанию). Допустимы также `run` или `init`, но выбор должен быть единообразным по всему проекту.
- **Запрещено** объявлять методы класса через лямбда-синтаксис (стрелочные функции). Используйте обычные методы.

  ```typescript
  // ❌ Плохо
  class Example {
    hello = () => {
      console.log("Hello");
    };
  }

  // ✅ Хорошо
  class Example {
    public hello() {
      console.log("Hello");
    }
  }
  ```

### 4. Код

- Избегайте дублирования кода (DRY). Выносите повторяющиеся части в утилиты или общие функции.
- Снижайте уровень вложенности: используйте ранний `return`, `continue`, `break`.
- Используйте **пояснительные переменные** для сложных условий.

  ```typescript
  const transferAllowed =
    hasSufficientBalance(account, amount) && account.isActive();
  if (transferAllowed) {
    // ...
  }
  ```

- Не оставляйте закомментированный код.
- Избегайте «магических чисел» и «магических строк» – выносите их в именованные константы.
- **Желательно** не опускать фигурные скобки у условных операторов и циклов. Исключение – однострочные `return` или `throw`, когда это завершает выполнение функции.

  ```typescript
  // Неплохо
  if (condition) doSomething();

  // Лучше
  if (condition) {
    doSomething();
  }

  // Допустимо
  if (!condition) return;
  ```

- Отступы – **2 пробела** (стандарт команды).

### 5. Импорты и экспорты

- **Запрещён** одновременный импорт и экспорт (`export import ...`). Это приводит к путанице.
- Типы (интерфейсы, абстрактные классы, type-алиасы) импортируйте с помощью `import type`.

  ```typescript
  import type { SomeInterface, SomeType } from "./types";
  ```

- Сортируйте импорты в следующем порядке:
  1. Инициализирующие импорты (например, `import "dotenv/config"`).
  2. Импорты типов.
  3. Импорты данных (функции, классы, переменные, константы).
  4. Импорты статических файлов (`.json`, `.css` и т.п.).
- Используйте статический импорт (`import ... from ...`) вместо динамического (`require`), где это возможно.
- Избегайте `import * as name` – импортируйте только необходимое.

### 6. TypeScript

- **Желательно** использовать `const enum` вместо обычного `enum`, так как `const enum` полностью удаляется при компиляции и подставляет числовые значения, что уменьшает размер выходного кода. Обычные `enum` создают лишний JavaScript-объект.

  ```typescript
  // Предпочтительно
  const enum Direction {
    Up,
    Down,
    Left,
    Right,
  }

  // Избегайте
  enum Direction {
    Up,
    Down,
    Left,
    Right,
  }
  ```

- Явно указывайте возвращаемые типы функций, особенно для публичных методов.
- Используйте строгую типизацию (`strict: true` в tsconfig.json уже включено).

### 7. Компиляция и тестирование

- **Желательно** компилировать код ежедневно (или перед каждым коммитом) для раннего обнаружения ошибок.
- Все новые функции должны сопровождаться тестами (если в проекте есть тесты).
- Убедитесь, что существующие тесты проходят.

## Принципы SOLID

Проект следует принципам SOLID. Это означает:

- **S** (Single Responsibility): каждый класс и модуль отвечают за одну задачу.
- **O** (Open/Closed): классы открыты для расширения, но закрыты для модификации. Используйте наследование и композицию.
- **L** (Liskov Substitution): подклассы должны быть взаимозаменяемы с базовыми классами.
- **I** (Interface Segregation): интерфейсы должны быть узкоспециализированными.
- **D** (Dependency Inversion): зависимости должны быть от абстракций, а не от конкретных реализаций.

Пожалуйста, следуйте этим принципам при разработке новых компонентов.

## Процесс отправки изменений

1. **Форкните** репозиторий и создайте ветку для вашей работы.
   - Название ветки должно отражать суть изменения: `fix/issue-123`, `feature/add-json-formatter`.
2. Внесите изменения, следуя код-стайлу.
3. Убедитесь, что код компилируется без ошибок:
   ```bash
   npm run build
   ```
4. Если есть тесты, запустите их и убедитесь, что они проходят.
5. Обновите документацию, если добавили новую функциональность или изменили API.
6. Отправьте pull request в ветку `main`.
   - В описании PR укажите, что именно было сделано, и, если есть, ссылку на issue.

Мы рассмотрим ваш PR в ближайшее время. Если потребуются доработки, мы свяжемся с вами.

## Вопросы

Если у вас есть вопросы, вы можете открыть issue или связаться с автором через email, указанный в package.json.

Ещё раз спасибо за ваш вклад!