ktlint і detekt: практичний досвід інтеграції в Android проєкт
Всім привіт! Я — Олеся, Android Developer. Коли команда, в якій я працювала, за пів року зросла втричі, з’явилася потреба не тільки в інтеграції статичних аналізаторів коду, а й наявність чітких процесів, які б контролювали дотримання правил всієї команди і покращували роботу.
У цій статті я зосереджуся не тільки на технічній реалізації, а і на процесах, інтегрованих у командну роботу, оскільки технічні деталі вже описані в багатьох публікаціях. Ця стаття допоможе побудувати план дій для інтеграції статичних аналізаторів в Android проект з 0 на прикладі мого досвіду.
Огляд доступних інструментів
На даний момент найпопулярнішими статичними аналізаторами для Kotlin коду є ktlint і detekt.
ktlint
ktlint (github.com/pinterest/ktlint) — це код лінтер і форматер коду, розроблений Pinterest.
Він відповідає за відступи, пробіли, форматування. В проєкті ми використовували ktlint-gradle від Jonathan Leitschuh — це gradle plugin, який інтегрує ktlint у вашу Gradle систему збірки; він спрощує запуск ktlint задач в Gradle. Головною перевагою є автоформатування за допомогою команди ./gradlew ktlintFormat.
В ktlint є конфігураційний файл .editconfig, де можна вимикати неактуальні правила.
detekt
detekt (github.com/detekt/detekt) відповідає за те, який код ми пишемо (складність, паттерни, потенційні проблеми).
В detekt можна винести існуючі порушення в baseline файл. Під час перевірки detekt буде фокусуватись тільки на новому коді. Наша стратегія — поступово рефакторити легасі-код, зменшуючи baseline файл.
У detekt використовується конфігураційний файл detekt.yml, який дозволяє додавати кастомні правила та налаштовувати їх поведінку, зокрема виключати правила для окремих файлів або функцій з певними анотаціями.
Detekt обрали, бо він має близько 200+ правил для коду, є можливість їх кастомізовувати і писати власні правила, також він є open-source рішенням з екосистемою плагінів detekt.dev/marketplace включно з Compose Rules mrmans0n.github.io/compose-rules/detekt.
Навіщо обидва?
Разом вони доповнюють один одного, але мають певні перетини у функціональності:
- ktlint відповідає за те, як виглядає код (форматування, відступи, пробіли)
- detekt відповідає за те, який код ми пишемо (складність, паттерни, потенційні проблеми)
Наша стратегія:
- Використовуємо ktlint для автоматичного форматування коду (відступи, пробіли, переноси рядків тощо).
- Якщо правила дублюються з ktlint і не виправляються автоматично, наприклад, MaxLineLength, то вимикаємо їх в ktlint і використовуємо для них detekt.
- Щоб у всіх був однаковий стиль коду зберігаємо конфігураційні файли detekt.yml і .editconfig в репозиторії.
Перший етап: визначення актуальних правил, ігнорування легасі коду
detekt
На початку інтеграції за допомогою detekt репорту було визначено обсяг порушень. Їх кількість в нашому проєкті понад 4000 порушень. Команду було ознайомлено з правилами, в результаті обговорення домовилися внести корективи/вимкнути неактуальні правила.
Правила detekt, що були підкореговані
Складність класів і методів
Detekt має дуже маленькі дефолтні значення для кількості функцій у класі, тому їх було збільшено:
LongMethod: active:true threshold:60 ignoreAnnotated: - Preview # Composable Preview можуть бути довшими TooManyFunctions: active:true excludes: -'**/test/**' -'**/androidTest/**' -'**/*Presenter.kt' # Для старого MVP коду thresholdInFiles:20 # Збільшили з 11 thresholdInClasses:15 # Збільшили з 11 thresholdInInterfaces:15 # Збільшили з 11 thresholdInObjects:11 thresholdInEnums:11 ignoreAnnotatedFunctions:['Preview'] LongParameterList: active:true functionThreshold:12 # Збільшили з 6 constructorThreshold:12 # Збільшили з 7 ignoreDefaultParameters:true # Дуже зручно для composable елементів, так як писали власну дизайн систему правило стало актуальним https://detekt.dev/docs/introduction/compose/#longparameterlist-for-compose ignoreDataClasses:true excludes:['**/*Entity.kt'] # Api/db entities можуть мати багато параметрів ignoreAnnotated: -'dagger.Provides' -'dagger.Binds' -'javax.inject.Inject' -'dagger.assisted.AssistedInject'
Magic Numbers
Для дизайн системи, міграцій, Preview magic numbers допустимі:
style: MagicNumber: active:true excludes: -'**/test/**' -'**/*.kts' -'**/designsystem/theme/**', # Design system містить в собі примітиви - значення кольорів, які не треба виносити в константи, бо val black: Color = Color(0xFFFFFFFF) - виносити 0xFFFFFFFF значення - це overengineering -'**/migration/Migration*.kt' # Database migrations ignoreNumbers: -'-1' -'0' -'1' -'2' ignoreHashCodeFunction:true ignorePropertyDeclaration:false ignoreConstantDeclaration:true ignoreCompanionObjectPropertyDeclaration:true ignoreAnnotated: - Preview # Composable Preview ignoreNamedArgument:true ignoreExtensionFunctions:true
Тести
Для тестів по дефолту вимкнено достатньо нерелевантних для них правил, таких як FunctionNaming, MagicNumber, і тд. Вирішили доповнити цей список такими правилами:
LargeClass: # Для тестових класів це є нормальним active: true threshold: 600 excludes: [ '**/test/**', '**/androidTest/**', '**/commonTest/**', '**/jvmTest/**', '**/androidUnitTest/**', '**/androidInstrumentedTest/**', '**/jsTest/**', '**/iosTest/**' ] LongParameterList: # Може бути великим для test data builders active: true functionThreshold: 12 constructorThreshold: 12 ignoreDefaultParameters: false ignoreDataClasses: true ignoreAnnotatedParameter: [] excludes: ['**/test/**', '**/androidTest/**', '**/commonTest/**', '**/jvmTest/**', '**/androidUnitTest/**', '**/androidInstrumentedTest/**', '**/jsTest/**', '**/iosTest/**', '**/*Entity.kt'] MaxLineLength: # Треба часто писати моки, що зручно тримати на 1 рядку active: true maxLineLength: 120 excludePackageStatements: true excludeImportStatements: true excludeCommentStatements: false excludeRawStrings: true excludes: [ '**/test/**', '**/androidTest/**', '**/commonTest/**', '**/jvmTest/**', '**/androidUnitTest/**', '**/androidInstrumentedTest/**', '**/jsTest/**', '**/iosTest/**' ]
Compose-специфічні правила
ComposeDetekt — це плагін для detekt, що додає правила для компоуз коду. При його додаванні треба було виключити конфліктуючі правила.
Виключили правило CompositionLocalAllowlist для модуля design-system , так як це рекомендований спосіб використання примітивів дизайн системи
developer.android.com/...sitionlocal#creating-apis .
CompositionLocalAllowlist: active: true excludes: ['**/design-system/**']
Кастомні правила
Також detekt дає можливість писати кастомні правила. З командою також варто зібратися і обговорити правила, які спільні для всього проєкту і їх перевірку можна автоматизувати. Наприклад, одне з таких правил — присутність номеру тікету в коментарі todo, яке було узгоджено додати в проєкт.
ktlint
На початку інтеграції ktlint було автовиправлено всі порушення за допомогою команди ./gradlew ktlintFormat. Ті правила, що не можуть бути автовиправлені, були вимкнені і включені в detekt, щоб мати single source of truth.
Неактуальні правила ktlint для нас
Наш .editorconfig виглядає так:
[*.{kt,kts}]
ktlint_standard_property-naming= disabled
ktlint_standard_no-wildcard-imports = disabled
ktlint_standard_function-naming= disabled
ktlint_standard_filename= disabled
ktlint_standard_max-line-length= disabled
ktlint_standard_function-signature= disabled
ktlint_standard_annotation= disabled
Чому ці правила відключені:
- property-naming, function-naming, filename, max-line-length, no-wildcard-imports, function-signature — ці правила обробляє detekt (single source of truth).
- annotation — це правило переносило
@Injectанотацію на новий рядок і додавало зайвий відступ для коду в класі, що суперечило налаштуванням форматування відступів Android Studio.

Другий етап: автоматизація
Інтеграція GitLab CI job
Паралельне виконання ktlint і detekt
Перший етап у CI— це паралельний запуск ktlint і detekt перед виконанням інших етапів, таких як unit-тести та збірка. Якщо одна з цих перевірок падає, наступні етапи не запускаються.
# .gitlab-ci.yml stages: - code_check - test - build code_check:ktlint: stage: code_check script: - ./gradlew ktlintCheck --continue rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /^dev$|^release-.*$/' when: on_success - when: never artifacts: paths: - '**/build/reports/ktlint/**' when: always expire_in: 1 week allow_failure: false code_check:detekt: stage: code_check script: - ./gradlew detekt --continue rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME =~ /^dev$|^release-.*$/' when: on_success - when: never artifacts: paths: - '**/build/reports/detekt/**' when: always expire_in: 1 week allow_failure: false
Чому це важливо:
- Швидкий feedback — розробник дізнається про проблеми за ~3-4 хв
- Економія ресурсів — не запускаємо тести, якщо код не відповідає стандартам
Автоматизація підрахунку технічного боргу
Кожного тижня запускався CI job, що перегенеровує baseline файл для всіх модулів і рахує кількість видалених строчок. Це допомагає відслідковувати прогрес рефакторингу правил.
При необхідності розробнику проігнорувати порушення — використовуємо @Suppress. Baseline файл в нас створений для легасі коду і перегенеровується тільки раз в тиждень — або при додаванні нових плагінів, наприклад, при додаванні плагіну Compose Detekt зʼявилися нові порушення, які треба виправляти поступово.
Git hooks
В проєкт було інтегровано git hooks, що автоматично проганяють ktlintCheck, ktlintFormat і detekt команди при комітах.
Git hook є оптимізованим — відпрацьовує лише по зміненим файлам.
Приклад, як це можна реалізувати:
При коміті hook збирає список staged .kt файлів через git diff --cached і передає їх у Gradle tasks через property -PchangedFiles. Далі кожен інструмент отримує тільки свої файли:
- ktlint підтримує це з коробки через вбудований параметр
internalKtlintGitFilter - detekt потребує невеликої конфігурації в
build.gradle.kts
Конфігурація для detekt в build.gradle.kts :
subprojects {
tasks.withType<Detekt>().configureEach {
if (project.hasProperty("changedFiles")) {
val projectPath = projectDir.toPath()
val changedFiles = (project.property("changedFiles") as String)
.lineSequence()
.filter { it.isNotBlank() }
.map { it.trim() }
.mapNotNull {
rootProject.rootDir.resolve(it)
.takeIf { f -> f.toPath().startsWith(projectPath) }
}
.toList()
enabled = changedFiles.isNotEmpty()
if (enabled) setSource(files(changedFiles))
}
}
}
Виклик з хука:
echo "🔧 Running ktlint format..." ./gradlew $KTLINT_FORMAT_TASKS --daemon --quiet -PchangedFiles="$EXISTING_STAGED_FILES" echo "✅ Running ktlint check..." ./gradlew $KTLINT_CHECK_TASKS --daemon --quiet -PchangedFiles="$EXISTING_STAGED_FILES" echo "🔎 Running detekt..." ./gradlew $DETEKT_TASKS --daemon --quiet -PchangedFiles="$EXISTING_STAGED_FILES"
Третій етап: модифікація правил, а не ігнорування
- У нас проєкт зростав, архітектура змінювалася, тому важливо не просто писати
@Suppressдля класу, а вносити відповідні зміни в detekt правила, якщо ми міняємо архітектуру.
Приклад: Database Migrations
Раніше міграції для бази даних знаходилися в одному файлі. Так як у нас їх стало багато — почали виносити в окремий файл кожну міграцію — і файли були названі відповідно типу Migration_24_25.kt, і треба було модифікувати правило MagicNumber.
Замість того, щоб писати кожний раз @Suppress, були внесені корективи в конфігурацію:
style: MagicNumber: active:true excludes: -'**/migration/Migration*.kt' # У міграціях є version numbers
- Коли ми додаємо код в і так великий метод , який вже є в baseline файлі, то detekt підсвітить , що тут цей код суперечить правилу LongMethod — важливо його порефакторити а не написати
@Suppress- так ми поступово рефакторимо старий код і зменшуємо baseline файл.
Адаптація команди
Для ознайомлення команди було проведено 2 міти — на першому обговорювалися загальні правила detekt і ktlint, на другому правила compose plugin для detekt. Було обґрунтована їхня актуальність — на прикладах показано порушення і способи їх вирішення. Були складені домовленості, як ми працюємо з тим чи іншим правилом.
Всі зміни в detekt.yml обговорювалися з командою — пишеться повідомлення з запропонованими змінами і зміни вносяться в конфігураційний файл після апруву більшою частиною команди. Всі зміни вирішуються голосуванням.
Якщо в команді з’являються суперечності, стосовно наявних правил, важливо щоб всі/більшість сказали своє бачення про конкретне правило, привели аргументи «за» та «проти». Додатково можна влаштувати невеликий міт, для наочної демонстрації переваг/недоліків.
Наприклад, у нашій команді була суперечність з приводу правила LongParameterList, було запропоновано його вимкнути, бо воно тільки створює шум і не несе цінності. Після детального обговорення, наведених прикладів коду, де це правило добре підсвічує проблемний код, який має порефакторитися, було вирішено збільшити кількість параметрів, та залишити правило увімкненим.
За detekt i ktlint призначено одного відповідального — людина, що інтегровувала ці статичні аналізатори. Вона в більшості випадків вносить правки в цей файл. Якщо хтось інший вносить правки, то відповідальний долучається до ревʼю коду.
Для нових розробників складено онбординг — документ, що описує налаштування статичних аналізаторів, вимкнені правила, як виправляти проблеми, що підсвічуються аналізаторами, роботу з їхніми репортам, найкращі практики роботи з ними і написання коду. Цей документ оновлюється по мірі появи нової інформації.
Підсумок: що ми отримали після інтеграції
Метрики за 6 місяців
Tech Debt Reduction:
За 6 місяців ми досягли reduction: ~69%
Developer Experience:
- Кількість коментарів про стиль коду: майже 0.
Code Quality:
- Зменшення cognitive complexity у ~300 методах
Best Practices:
Конфігурація:
- Зберігайте конфігураційні файли в git репозиторії
Baseline:
- Baseline тільки для легасі коду
- Регулярна регенерація для відслідковування результатів
Автоматизація:
- Git hooks для локальної перевірки
- Перевірка тільки змінених файлів
- Паралельні jobs на CI
- Блокування pipeline при помилках
Команда:
- Навчання та онбординг нових розробників
- Чіткі guidelines для code review
- Залишай код кращим, ніж він був
Висновки
Статичні аналізатори — це інструменти, які потребують плану інтеграцій процесів в команду.
Ключові takeaways:
- Фокусуйтесь не тільки на інструментах, а і на процесах — інтегруйте чіткі процеси в командну роботу.
- Користуйтеся автоматизацією — CI jobs, git hooks.
- Single source of truth — делегуйте повторювальні правила одному інструменту, тримайте конфігурації в репозиторії.
- Будьте гнучкими — налаштовуйте правила під вашу команду та архітектуру, рефакторьте старий код, коли з ним працюєте.
- Вимірюйте прогрес — метрики допомагають бачити цінність.
- Оновлюйте конфігурацію — коли архітектура змінюється, правила мають змінюватись разом.
Наш досвід показав, що інтеграція статичних аналізаторів зробила код кращим, code reviews швидшими, а команду продуктивнішою.
Найважливіше — це не просто встановити інструменти, а побудувати культуру якості коду, де команда розуміє цінність цих процесів і активно їх використовує.
Корисні посилання:
Немає коментарів
Додати коментар Підписатись на коментаріВідписатись від коментарів