Документация в Swift: как писать код, который говорит сам за себя

Почему документация — это суперсила разработчика

Представьте: вы открываете чужой проект на Swift через полгода после его написания. Код работает, но понять, зачем автор сделал именно так, а не иначе — невозможно. Комментариев нет, названия переменных в стиле a1, temp2. Знакомо?

Хорошая документация — это не просто вежливость к будущему себе. Это инструмент, который экономит часы дебаггинга, ускоряет онбординг новых разработчиков и превращает хаос в стройную систему. В этой статье мы разберём лучшие практики документирования Swift-кода, от базовых комментариев до продвинутого DocC.

Основы: от простых комментариев к осмысленным описаниям

//, /// и /* */ — когда что использовать

В Swift есть три типа комментариев, и каждый — для своей задачи:

• Однострочные // — для быстрых заметок, TODO или временных отключений кода. Не злоупотребляйте: если комментарий объясняет очевидное — он лишний.
• Многострочные /* */ — для блоков пояснений или отключения целых кусков кода при отладке.
• Документирующие /// — это ваш главный инструмент. Xcode автоматически подхватывает их и показывает в Quick Help.

/// Вычисляет площадь круга по радиусу.
/// - Parameter radius: Радиус круга в метрах.
/// - Returns: Площадь в квадратных метрах.
/// - Throws: `InvalidInputError.negativeRadius`, если radius < 0.
func areaOfCircle(radius: Double) throws -> Double {
    guard radius >= 0 else {
        throw InvalidInputError.negativeRadius
    }
    return Double.pi * radius * radius
}

Плохой vs хороший комментарий

Сравните два подхода:

// ПЛОХО: Очевидный комментарий
// Увеличиваем счётчик на 1
counter += 1

// ХОРОШО: Объясняем "почему"
// Используем инкремент, потому что это критический участок
// производительности, а операция ++ в Swift устарела
counter += 1

Золотое правило: комментарий должен отвечать на вопрос «почему», а не «что» делает код. Код сам должен быть читаемым, чтобы «что» было понятно без слов.

DocC — документация нового поколения

Что такое DocC и почему это must-have

С появлением Xcode 13 Apple представила DocC (Documentation Compiler) — инструмент, который превращает ваши /// комментарии в красивую, интерактивную документацию прямо внутри Xcode и на вебе. Больше никаких PDF-файлов и вики-страниц, которые устаревают за неделю.

Как использовать DocC в проекте

1. Настройка: В Xcode выберите Product → Build Documentation. DocC сам соберёт все документированные символы.
2. Ссылки внутри документации: Используйте `` для ссылок на другие типы:

/// Используйте ``NetworkManager`` для отправки запросов.
/// Подробнее в статье <doc:NetworkGuide>.

3. Markdown-возможности: DocC поддерживает заголовки, списки, таблицы, изображения и даже диаграммы на Mermaid:

/// # Алгоритм работы
/// 1. Проверка кэша
/// 2. Если нет — запрос к серверу
/// 3. Сохранение результата

Создаём документацию для целого модуля

Добавьте файл Documentation.docc в корень проекта. Внутри — структура в Markdown:

// MyFramework.docc/MyFramework.md
# ``MyFramework``

Асинхронная библиотека для работы с сетью.

## Topics

### Основные компоненты
- ``NetworkManager``
- ``RequestBuilder``

### Расширения
- <doc:CustomizingRequests>

Продвинутые техники: пишем документацию, которую читают

Структурируем по ролям

Не весь код требует одинаковой детализации. Разделите документацию на уровни:

• API-документация — для публичных методов и протоколов (обязательно).
• Внутренняя документация — для сложных алгоритмов (рекомендуется).
• Архитектурная документация — описание модулей и их взаимодействия (для больших проектов).

Примеры в документации — ваше секретное оружие

DocC позволяет встраивать примеры кода прямо в описание:

/// Создаёт анимированное появление view.
///
/// Пример использования:
///
/// ```swift
/// let view = MyCustomView()
/// view.fadeIn(duration: 0.5)
/// ```
///
/// - Parameter duration: Длительность анимации в секундах.
func fadeIn(duration: TimeInterval) { ... }

Документируем async/await и ошибки

Современный Swift полон асинхронности. Не забудьте документировать throws и async:

/// Загружает данные пользователя по ID.
/// - Parameter id: Уникальный идентификатор пользователя.
/// - Returns: Модель ``User``.
/// - Throws: ``NetworkError.notFound`` если пользователь не существует,
///   ``NetworkError.timeout`` при превышении времени ожидания.
func fetchUser(id: UUID) async throws -> User

Инструменты и автоматизация

Держим документацию в актуальном состоянии

Ручная проверка — путь к устаревшей документации. Используйте:

• SwiftLint — правило missing_docs заставит документировать все public-символы.
• Jazzy — альтернатива DocC для генерации HTML-документации (если нужна совместимость со старыми проектами).
• GitHub Actions — автоматическая сборка документации при каждом пуше:

# .github/workflows/docs.yml
name: Build Documentation
on: [push]
jobs:
  build:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v3
    - name: Build DocC
      run: |
        xcodebuild docbuild -scheme MyApp \
          -derivedDataPath /tmp/docbuild \
          -destination 'platform=iOS Simulator'
    - name: Upload Artifact
      uses: actions/upload-artifact@v3
      with:
        name: documentation
        path: /tmp/docbuild/Build/Products/Debug-iphonesimulator/MyApp.doccarchive

Документация для SwiftUI

Для SwiftUI-компонентов документация особенно важна, так как модификаторы могут менять поведение кардинально:

/// Кастомная кнопка с эффектом нажатия.
///
/// Используйте этот компонент вместо стандартной `Button`,
/// когда нужна более ги