refactor: update architecture documentation and add commenting standards

docs/development/commenting-standard.md

@@ -0,0 +1,80 @@
+# Стандарт комментирования 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. Актуальность
+
+- Комментарий, не соответствующий коду — это дезинформация.
+- При изменении контракта функции или логики типа, комментарий **обязан** быть обновлён в том же коммите.
+- Устаревшие комментарии должны безжалостно удаляться.