Стандарт комментирования 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).
- Комментарии ради комментариев.

Пример:

/// Обрабатывает входящий аудио-фрейм и извлекает наблюдения.
///
/// - 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. Актуальность

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

4.6 KiB Raw Blame History