Ktlint 도입하기

Ktlint란?

: Kotlin의 코드 스타일 검사 및 포맷팅 도구. 팀 내에서 일관된 코드 스타일을 유지하기 위해 사용된다.

• 공식 Kotlin 코딩 컨벤션을 기반으로 동작
• Gradle 플러그인으로 쉽게 통합 가능
• .editorconfig를 통해 프로젝트별 규칙 커스터마이징 가능

왜 도입했는가?

• 일관된 코드 스타일: 팀원들마다 다른 코드 스타일을 통일
  • 가독성 향상 및 코드 리뷰 시 스타일에 대한 논쟁을 줄일 수 있다
• 자동화된 포맷팅: 수동으로 스타일을 맞출 필요 없이 명령어 하나로 자동 포맷팅

설정 방법

1. build.gradle 설정

Gradle 프로젝트에 ktlint 플러그인을 추가한다.

plugins {
    id("org.jlleitschuh.gradle.ktlint") version "11.0.0"
}

ktlint {
    version.set("0.50.0")
    debug.set(false)
    verbose.set(true)
    android.set(false)
    outputToConsole.set(true)
    ignoreFailures.set(false)
}

2. .editorconfig 설정

프로젝트 루트에 .editorconfig 파일을 생성하여 코드 스타일 규칙을 정의한다. (팀 내 컨벤션에 따라 커스터마이징)

[*.{kt,kts}]
# 들여쓰기 스타일
indent_style = space
indent_size = 4

# 최대 라인 길이
max_line_length = 120

# import 구문 정렬
ij_kotlin_imports_layout = *,java.**,javax.**,kotlin.**,^

# 기타 규칙들
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true

++) Git Pre-commit Hook 설정

.git/hooks/pre-commit 파일을 생성하여 커밋 전 자동으로 lint 검사를 실행하도록 설정한다. (프로젝트 모든 인원이 이 설정을 하도록 의미가 있음)

#!/bin/sh
######## KTLINT-GRADLE HOOK START ########

CHANGED_FILES="$(git --no-pager diff --name-status --no-color --cached | awk '$1 != "D" && $NF ~ /\.kts?$/ { print $NF }')"

if [ -z "$CHANGED_FILES" ]; then
    echo "No Kotlin staged files."
    exit 0
fi;

echo "Running ktlint over these files:"
echo "$CHANGED_FILES"

diff=.git/unstaged-ktlint-git-hook.diff
git diff --color=never > $diff
if [ -s $diff ]; then
  git apply -R $diff
fi

./gradlew --quiet ktlintCheck -PinternalKtlintGitFilter="$CHANGED_FILES"
gradle_command_exit_code=$?

echo "Completed ktlint run."


if [ -s $diff ]; then
  git apply --ignore-whitespace $diff
fi
rm $diff
unset diff

echo "Completed ktlint hook."
exit $gradle_command_exit_code
######## KTLINT-GRADLE HOOK END ########

실행 권한을 부여

chmod +x .git/hooks/pre-commit

사용법

코드 스타일 검사

./gradlew ktlintCheck

프로젝트의 모든 Kotlin 파일에 대해 스타일 검사를 수행한다. 문제가 있으면 에러 메시지와 함께 어떤 파일의 몇 번째 라인에서 문제가 발생했는지 알려준다.

자동 포맷팅

./gradlew ktlintFormat

검사를 통과하지 못한 코드를 자동으로 수정해준다. 대부분의 스타일 문제는 이 명령어로 해결 가능하다.

긴급 커밋 (Hook 우회)

git commit --no-verify -m "긴급 수정"

Pre-commit hook을 우회하여 커밋할 수 있다. 하지만 가급적 사용하지 않는 것을 권장

장점

• 일관성: 팀 전체가 동일한 코드 스타일을 따르게 되어 가독성이 향상된다
• 자동화: 수동으로 스타일을 체크하고 수정할 필요가 없다
• 사전 방지: Pre-commit hook을 통해 잘못된 스타일의 코드가 리포지토리에 올라가는 것을 방지
• 리뷰 효율성: 코드 리뷰 시 스타일에 대한 지적이 줄어들어 로직에 집중할 수 있다

신경써야 할 것

• 초기 적용 시 수정량이 많을 수 있다: 기존 코드가 많은 프로젝트에 처음 도입하면 많은 파일이 수정될 수 있다
• 빌드 시간 증가: ktlint 포메팅이 꽤나 오래걸려서 번거롭긴함..
• 와일드카드 임포트같은건 자동수정이 안돼 수동으로 해줘야 함.

Reference)

• https://github.com/pinterest/ktlint
• https://github.com/JLLeitschuh/ktlint-gradle