# Стандарт комментирования Mastermind

Этот документ устанавливает правила документирования и комментирования кода в Swift-проекте Mastermind.

## 1. Язык и стиль

- **Язык**: Все комментарии, документация DocC и пометки TODO/FIXME пишутся на **русском языке**.
- **Стиль**: Лаконичный, технический, без лишних слов. Используйте DocC для всех семантически значимых деклараций.

## 2. Обязательный DocC

DocC (тройной слэш `///`) обязателен для следующих элементов:

- Все типы (Struct, Class, Enum, Actor, Protocol).
- Все требования протоколов.
- Все функции, методы и инициализаторы.
- Все свойства (properties), имеющие самостоятельный доменный или технический смысл.

**Исключения**:

- Локальные переменные внутри функций.
- Очевидные элементы тестовых фикстур (если их смысл понятен из названия).
- Однородные `enum cases` (можно документировать одной группой перед перечислением).

## 3. Формат DocC (Concise Semantic DocC)

**Правила**:

- Первая строка — одно предложение, описывающее роль или контракт элемента.
- Секции `- Parameters:`, `- Returns:`, `- Throws:` добавляются только если они несут дополнительную информацию.
- **Запрещено**:
  - Пустые секции.
  - Дословный пересказ сигнатуры (например, `/// Возвращает строку` для функции `func getString() -> String`).
  - Комментарии ради комментариев.

**Пример**:

```swift
/// Обрабатывает входящий аудио-фрейм и извлекает наблюдения.
///
/// - Parameter frame: PCM данные в формате 16 кГц моно.
/// - Throws: `AudioError.invalidFormat`, если данные повреждены.
func process(frame: PCMFrame) throws { ... }
```

## 4. Внутренние комментарии (Inline)

Используйте двойной слэш `//` только в следующих случаях:

- **Почему (Rationale)**: Объяснение нетривиального архитектурного решения.
- **Инварианты**: Описание условий, которые должны соблюдаться в этом блоке кода.
- **Безопасность и Concurrency**: Пояснения по поводу владения данными или специфики потоков.
- **OS Quirks**: Описание обходных путей (workarounds) для особенностей macOS/AppKit.

**Запрещено**:

- "Narrating comments" — пересказ того, что делает код (например, `// увеличиваем счетчик`).
- Закомментированный код (удаляйте его, история есть в Git).

## 5. Навигация и пометки

### MARK

Используйте `// MARK: -` для разделения больших файлов на смысловые секции.

- Группируйте методы расширений (extensions) по протоколам, которым они соответствуют.
- Не используйте MARK для одиночных методов.

### TODO и FIXME

Использование этих пометок разрешено только с указанием ссылки на задачу (issue).

- `// TODO(#123): Описание задачи и что именно нужно сделать.`
- `// FIXME(#456): Описание нарушения или риска, который нужно устранить.`

## 6. Актуальность

- Комментарий, не соответствующий коду — это дезинформация.
- При изменении контракта функции или логики типа, комментарий **обязан** быть обновлён в том же коммите.
- Устаревшие комментарии должны безжалостно удаляться.