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