들어가며: Ktlint와 .editorconfig

Ktlint는 Kotlin 코드 스타일을 검사하고 자동으로 포맷팅해주는 도구입니다. Ktlint의 기본 철학은 “설정 없는(no configuration)” 방식이고, 팀 안에서 코드 스타일 논쟁을 줄이는 데 도움이 됩니다.

하지만 때로는 프로젝트의 기존 규칙이나 팀의 합의에 따라 특정 스타일 가이드를 따르거나 일부 규칙을 변경해야 할 필요가 있습니다. Ktlint는 이러한 요구사항을 위해 .editorconfig 파일을 통한 커스터마이징을 지원합니다. .editorconfig는 다양한 에디터와 IDE에서 코드 스타일을 일관되게 유지하기 위한 표준 파일 형식으로, Ktlint는 이 파일을 읽어 설정을 적용합니다.

이 글에서는 .editorconfig 파일로 Ktlint 동작을 프로젝트에 맞게 조정하는 방법을 정리합니다.

1. 기본 코드 스타일 변경하기

Ktlint 1.0 버전부터 기본 코드 스타일은 ktlint_official로 지정되어 있습니다. 만약 IntelliJ IDEA의 기본 포맷터나 Android 개발 스타일 가이드를 따르고 싶다면, .editorconfig 파일에 다음과 같이 ktlint_code_style 속성을 추가하여 변경할 수 있습니다.

# 프로젝트 루트 디렉터리에 .editorconfig 파일을 생성하거나 기존 파일에 추가합니다.

# Kotlin 파일에 적용될 규칙임을 명시합니다.
[*.{kt,kts}]

# 원하는 코드 스타일을 지정합니다.
# 선택 가능: intellij_idea, android_studio, ktlint_official (기본값)
ktlint_code_style = intellij_idea

2. 특정 규칙 비활성화하기

가장 흔한 커스터마이징 요구사항은 특정 규칙을 비활성화하는 것입니다. 예를 들어, 팀에서 와일드카드 임포트(import com.example.*)를 허용하기로 합의했다면, no-wildcard-imports 규칙을 비활성화할 수 있습니다.

규칙을 비활성화하는 형식은 ktlint_<규칙세트ID>_<규칙ID> = disabled 입니다.

[*.{kt,kts}]

# standard 규칙 세트의 no-wildcard-imports 규칙을 비활성화합니다.
ktlint_standard_no-wildcard-imports = disabled

# experimental 규칙 세트의 some-rule 규칙을 비활성화합니다.
ktlint_experimental_some-rule = disabled

규칙 ID는 어떻게 찾을 수 있을까요?

규칙을 비활성화하려면 정확한 규칙 ID를 알아야 합니다. 찾는 방법은 다음과 같습니다.

방법 1: IntelliJ Ktlint 플러그인 사용하기

IntelliJ IDEA를 사용한다면 Ktlint 플러그인을 설치하는 방법이 편합니다. 플러그인을 설치하면 코드 스타일 위반 위치에 경고가 표시되고, 경고 메시지에서 규칙 ID를 확인할 수 있습니다.

위 이미지처럼, 여러 개의 공백 사용을 금지하는 규칙에 대한 경고가 표시되면, 메시지 끝에 있는 괄호 안의 (standard:no-multi-spaces) 부분을 통해 규칙 세트 ID가 standard이고 규칙 ID가 no-multi-spaces임을 알 수 있습니다. 따라서 이 규칙을 비활성화하려면 .editorconfig에 ktlint_standard_no-multi-spaces = disabled를 추가하면 됩니다.

방법 2: Ktlint CLI 출력 확인하기

커맨드 라인에서 ktlint 명령을 실행하여 코드 스타일을 검사하면, 각 위반 사항과 함께 규칙 ID가 출력됩니다. 이를 통해서도 정확한 ID를 확인할 수 있습니다.

방법 3: 공식 문서 참고하기

Ktlint 공식 규칙 문서에서 현재 사용 가능한 모든 표준 규칙 목록과 각 규칙의 ID를 확인할 수 있습니다.

3. 추가 설정 팁

실험적 규칙(Experimental Rules) 활성화

Ktlint는 아직 표준으로 채택되지 않았지만 유용할 수 있는 실험적 규칙들을 제공합니다. 이 규칙들은 기본적으로 비활성화되어 있으며, 사용하려면 명시적으로 활성화해야 합니다.

[*.{kt,kts}]
ktlint_experimental = enabled

특정 규칙 세트 전체 비활성화

만약 standard 규칙 세트 전체를 사용하고 싶지 않다면, 다음과 같이 설정할 수 있습니다.

[*.{kt,kts}]
ktlint_standard = disabled

4. Git Hook을 이용한 자동화

팀원들이 커밋하기 전에 Ktlint 검사를 실행하도록 하면 코드 스타일을 더 일관되게 유지할 수 있습니다. ktlint-gradle 플러그인을 사용하는 경우 다음 명령어로 Git pre-commit hook을 설정할 수 있습니다.

./gradlew addKtlintCheckGitPreCommitHook

이 명령을 실행하면, git commit 시 자동으로 ktlintCheck 태스크가 실행되어 코드 스타일에 맞지 않는 코드가 커밋되는 것을 방지합니다.

결론

Ktlint는 기본 설정을 그대로 쓸 때 가장 단순하지만, 프로젝트 사정에 따라 규칙을 조정해야 할 때도 있습니다. 이때 .editorconfig에 변경 이유와 규칙을 명확히 남겨두면, 코드 스타일 설정 자체가 팀의 합의 문서 역할을 할 수 있습니다.

참고 자료:

이 글은 AI의 도움을 받아 교정 및 정리되었습니다.