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

Документация в Kotlin проектах: искусство быть понятым

Представьте: вы открываете чужой Kotlin-проект. Код красивый, лаконичный, но... вы не понимаете, зачем нужна эта функция и что она возвращает. Знакомо? А теперь представьте, что этот проект — ваш собственный, но спустя полгода. Документация в Kotlin — это не просто вежливость к коллегам. Это инвестиция в будущее вашего кода.

В этой статье мы разберём лучшие практики документирования Kotlin проектов. Вы узнаете, как использовать KDoc, Dokka и plain-комментарии так, чтобы ваш код говорил сам за себя. Поехали!

Почему документация в Kotlin — это не скучно?

Kotlin — язык, который создавался для людей. Он читается как английский, а его синтаксис избавляет от boilerplate кода. Но даже самый элегантный код может быть загадкой без документации. Особенно, когда речь идёт о:

• Сложных бизнес-логиках;
• Библиотеках и API, которые используют другие разработчики;
• Android-проектах с длинным жизненным циклом;
• Корпоративных решениях, где текучка кадров — норма.

Хорошая документация Kotlin решает три задачи: объясняет «что» делает код, «зачем» он это делает и «как» его использовать. Без неё вы рискуете получить код, который никто не хочет трогать (даже вы сами).

KDoc: главный инструмент документирования Kotlin

KDoc — это аналог JavaDoc для Kotlin. Он использует комментарии вида /** ... */ и поддерживает Markdown. Это стандарт де-факто для документации в Kotlin-проектах.

Вот как выглядит базовый пример:

/**
 * Рассчитывает скидку для пользователя на основе его статуса.
 *
 * @param price Исходная цена товара.
 * @param userLevel Уровень пользователя (BRONZE, SILVER, GOLD).
 * @return Итоговая цена со скидкой.
 * @throws IllegalArgumentException Если price отрицательный.
 */
fun calculateDiscount(price: Double, userLevel: UserLevel): Double {
    // логика
}

Обратите внимание: KDoc использует теги @param, @return, @throws. Но в отличие от JavaDoc, вы можете писать Markdown прямо внутри комментария. Это удобно для списков, ссылок и форматирования.

Лучшие практики KDoc

• Пишите для людей, а не для машин. Не дублируйте то, что очевидно из кода. Вместо // устанавливает значение напишите // Устанавливает значение, которое будет использоваться при расчёте налогов.
• Документируйте публичный API. Внутренние функции (private или internal) можно документировать кратко или не документировать вовсе.
• Используйте @see и @sample. Ссылайтесь на связанные функции или примеры использования.
• Не забывайте про @receiver для функций-расширений.

Dokka: превращаем комментарии в красивую документацию

Dokka — это генератор документации для Kotlin. Он умеет создавать HTML, Markdown, JavaDoc и даже документацию для мультиплатформенных проектов. Если вы пишете библиотеку или работаете в команде, Dokka — ваш лучший друг.

Установка проста. В build.gradle.kts добавьте плагин:

plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

Затем запустите команду:

./gradlew dokkaHtml

Dokka сгенерирует папку build/dokka/html с красивой документацией, включающей все ваши KDoc-комментарии, иерархию классов и даже ссылки на исходники.

Советы по Dokka

• Настройте логотип и описание проекта в dokkaConfiguration;
• Используйте @suppress, чтобы скрыть нежелательные элементы из документации;
• Для Android-проектов добавьте dokkaAndroidSources;
• Интегрируйте Dokka в CI/CD — пусть документация обновляется автоматически.

Комментарии в коде: когда и как использовать

Не вся документация должна быть в KDoc. Иногда простой комментарий внутри функции спасает день. Но здесь важно соблюдать баланс.

Плохой комментарий (не делайте так)

// увеличиваем i на 1
i++

Этот комментарий бесполезен: он объясняет то, что очевидно из кода. Хороший комментарий объясняет почему:

// Смещаем индекс на 1, потому что первый элемент — заголовок
i++

Когда писать комментарии

• Сложная логика. Алгоритмы, рекурсия, математические формулы.
• Бизнес-правила. «Скидка не применяется к товарам из категории "Премиум"».
• Костыли и хаки. Если вы обошли баг фреймворка — оставьте комментарий с ссылкой на issue.
• ТODO и FIXME. Но не забывайте их отслеживать и удалять.

Пример из реального проекта: документируем API

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

/**
 * Получает прогноз погоды для указанного города.
 *
 * Эта функция обращается к внешнему API и кэширует результат на 15 минут.
 * Если запрос не удался, возвращает последний известный прогноз.
 *
 * @param city Название города на русском или английском языке.
 * @param apiKey Ключ API для сервиса погоды.
 * @return [WeatherForecast] с текущим прогнозом.
 * @throws WeatherServiceException Если запрос не удался и кэш пуст.
 *
 * @sample com.example.weather.WeatherServiceTest.testGetForecast
 */
fun getForecast(city: String, apiKey: String): WeatherForecast {
    // ...
}

Обратите внимание: здесь есть @sample, который ссылается на тест. Это отличная практика — показывать, как использовать функцию на реальном примере. Dokka превратит эту ссылку в кликабельный элемент.

Документация для Android-проектов на Kotlin

Android-разработка на Kotlin имеет свою специфику. Вот несколько советов:

• Документируйте ViewModel и UseCases. Они часто содержат бизнес-логику, которую сложно понять без пояснений.
• Используйте @Composable для Jetpack Compose. Документируйте параметры композабл-функ