Как часто документируешь код

Отличный вопрос, который касается не только привычек, но и философии разработки. Мой подход к документации эволюционировал за годы и теперь строится на принципе «Документируй намерение, а не реализацию». Я следую гибкой, контекстно-зависимой стратегии, а не жесткому правилу «всегда» или «никогда».

Моя основная философия: Код как главная документация

Я твердо убежден, что чистый, выразительный код — это лучшая и самая актуальная документация. Поэтому мой приоритет — писать код, который документирует сам себя:

• Осмысленные имена: userRepository.fetchActive() вместо repo.get().
• Четкая архитектура: Следование принципам SOLID, Clean Architecture или MVVM, которые сами по себе задают структуру и понятны команде.
• Маленькие, сфокусированные функции/методы: Если метод делает одну вещь, его легко назвать и понять без комментариев.
• Система типов Kotlin: Использование sealed class для состояния, data class для моделей, что делает код типобезопасным и самодокументируемым.

Пример самодокументирующегося кода (Kotlin):

// ПЛОХО: Что такое "flag"? Что делает функция?
fun process(flag: Boolean) { ... }

// ХОРОШО: Намерение ясно из сигнатуры
fun updateUserProfile(
    userId: String,
    profileData: ProfileData
): Result<Unit>

Когда документация обязательна

Я следую строгому правилу добавлять документацию в следующих случаях:

1. Публичное API (Public / Internal)

Любой метод, класс или компонент, который будет использоваться другими разработчиками (в моей команде или из других модулей), должен иметь KDoc (аналог JavaDoc для Kotlin).

/**
 * Загружает аватар пользователя, применяет трансформации и кэширует результат.
 * @param userId Уникальный идентификатор пользователя.
 * @param size Требуемый размер изображения. Поддерживаются [AvatarSize.SMALL], [AvatarSize.MEDIUM].
 * @param placeholderResId ID ресурса-заглушки, отображаемой во время загрузки.
 * @return [Flow]<[AvatarResult]>, который эмитит состояние загрузки и результат.
 * @throws [NetworkUnavailableException] если устройство оффлайн.
 */
suspend fun loadAvatar(
    userId: String,
    @AvatarSize size: Int = AvatarSize.MEDIUM,
    @DrawableRes placeholderResId: Int = R.drawable.avatar_placeholder
): Flow<AvatarResult>

2. Сложная бизнес-логика или неочевидные алгоритмы

Если код реализует нетривиальную математику, специфичные бизнес-правила или оптимизацию, комментарий объясняет "почему", а не "что".

// Используем алгоритм Бойера-Мура для поиска шаблона в логе,
// так как стандартный String.indexOf() неэффективен на больших текстах.
private fun findPatternInLog(log: String, pattern: String): Int {
    // ... реализация алгоритма
}

3. Workarounds и временные решения

Любой код, который является обходным путем из-за бага в библиотеке, особенности ОС или временного ограничения, должен быть задокументирован с ссылкой на issue/bug tracker (JIRA, GitHub Issue).

// TODO: Удалить после обновления библиотеки X до версии 2.5+
// Баг: https://github.com/some/lib/issues/123
// Временное решение: вручную инвалидируем кэш при повороте экрана.
fun temporaryCacheFix() { ... }

4. Архитектурные решения и важные контракты

Я документирую ключевые архитектурные компоненты (например, базовые классы ViewModel, Repository, UseCase), используя README файлы в модулях или диаграммы (например, Mermaid в Markdown), чтобы объяснить поток данных и ответственность.

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

Я активно использую инструменты, чтобы сделать документацию частью процесса:

• KDoc/Dokka: Для генерации красивого HTML-сайта из комментариев в коде. Это must-have для библиотек или SDK.
• Lint-правила: Можно настроить проверки на наличие KDoc для публичных методов.
• PR-чеклисты: В команде у нас есть пункт "Документация добавлена для публичного API и сложных моментов".

Как часто? Итог

• Ежедневно: Я "документирую" кодом, постоянно рефакторя его для ясности.
• При каждом создании публичного API: Абсолютно всегда пишу KDoc.
• При столкновении с сложностью: Добавляю комментарий, объясняющий причину этой сложности.
• Периодически (раз в спринт/месяц): Проверяю актуальность существующих комментариев и README-файлов. Устаревшая документация хуже, чем ее отсутствие.

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