ktlint і detekt: практичний досвід інтеграції в Android проєкт

💡 Усі статті, обговорення, новини про Mobile — в одному місці. Приєднуйтесь до Mobile спільноти!

Всім привіт! Я — Олеся, 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 відповідає за те, який код ми пишемо (складність, паттерни, потенційні проблеми)

Наша стратегія:

  1. Використовуємо ktlint для автоматичного форматування коду (відступи, пробіли, переноси рядків тощо).
  2. Якщо правила дублюються з ktlint і не виправляються автоматично, наприклад, MaxLineLength, то вимикаємо їх в ktlint і використовуємо для них detekt.
  3. Щоб у всіх був однаковий стиль коду зберігаємо конфігураційні файли 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

Чому ці правила відключені:

  1. property-naming, function-naming, filename, max-line-length, no-wildcard-imports, function-signature — ці правила обробляє detekt (single source of truth).
  2. 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"

Третій етап: модифікація правил, а не ігнорування

  1. У нас проєкт зростав, архітектура змінювалася, тому важливо не просто писати @Suppress для класу, а вносити відповідні зміни в detekt правила, якщо ми міняємо архітектуру.

Приклад: Database Migrations

Раніше міграції для бази даних знаходилися в одному файлі. Так як у нас їх стало багато — почали виносити в окремий файл кожну міграцію — і файли були названі відповідно типу Migration_24_25.kt, і треба було модифікувати правило MagicNumber.

Замість того, щоб писати кожний раз @Suppress, були внесені корективи в конфігурацію:

style:
    MagicNumber:
    active:true
    excludes:
    -'**/migration/Migration*.kt'  # У міграціях є version numbers
  1. Коли ми додаємо код в і так великий метод , який вже є в 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:

  1. Фокусуйтесь не тільки на інструментах, а і на процесах — інтегруйте чіткі процеси в командну роботу.
  2. Користуйтеся автоматизацією — CI jobs, git hooks.
  3. Single source of truth — делегуйте повторювальні правила одному інструменту, тримайте конфігурації в репозиторії.
  4. Будьте гнучкими — налаштовуйте правила під вашу команду та архітектуру, рефакторьте старий код, коли з ним працюєте.
  5. Вимірюйте прогрес — метрики допомагають бачити цінність.
  6. Оновлюйте конфігурацію — коли архітектура змінюється, правила мають змінюватись разом.

Наш досвід показав, що інтеграція статичних аналізаторів зробила код кращим, code reviews швидшими, а команду продуктивнішою.

Найважливіше — це не просто встановити інструменти, а побудувати культуру якості коду, де команда розуміє цінність цих процесів і активно їх використовує.

Корисні посилання:

👍ПодобаєтьсяСподобалось3
До обраногоВ обраному1
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter