Kotlin 코딩 컨벤션, 어떻게 지킬까?

코틀린은 공식적으로 잘 정리된 코딩 컨벤션을 제공한다.
이 컨벤션을 지키면 누구나 코드를 쉽게 읽고, 이해하고, 유지보수할 수 있다.

• 새로운 프로젝트나 낯선 코드도 쉽게 이해할 수 있다.
• 외부 개발자나 팀원이 코드를 빠르게 파악하고 협업하기 쉬워진다.
• 코드의 동작 방식을 쉽게 추측할 수 있어 버그를 줄이고 품질을 높일 수 있다.
• 코드 병합, 리팩터링, 코드 이동 등 유지보수가 쉬워진다.

---

왜 코딩 컨벤션이 중요한가?

1. 코드 가독성 향상
   코딩 컨벤션을 지키면 일관된 스타일로 작성되어, 처음 보는 코드도 빠르게 이해할 수 있다.
2. 협업 효율 증가
   팀원 간 스타일이 통일되어 코드 리뷰 시간을 줄이고, 의사소통이 원활해진다.
3. 버그 감소
   일관된 코드 스타일은 코드 동작을 예측 가능하게 하여 잠재적인 버그 발생을 줄인다.
4. 유지보수 용이
   리팩터링, 코드 병합 시 충돌을 줄이고, 코드의 변경 및 확장 작업이 쉬워진다.
5. 자동화 도구와의 호환성
   ktlint 같은 린터와 포매터가 코딩 컨벤션을 기반으로 동작하기 때문에, 자동화된 검사와 수정이 가능하다.

 

Kotlin 공식 코딩 컨벤션 문서를 참고하자

Coding conventions | Kotlin

 

---

실전 적용 방법

 

우선 인텔리제이 포매터 설정하는 것에 습관을 들이자

• Preferences > Editor > Code Style > Kotlin 메뉴에서 설정 가능
• 저장 시 자동으로 컨벤션을 적용하도록 설정 가능

 

 

ktlint 도구를 사용한다

이번에 참여하게 된 사이드 프로젝트에 Ktlint를 도입하기로 하였다

 

Kotlin을 사용하다 보면 “이 코드 스타일이 맞나?” 라든가

“팀원마다 들여 쓰기나 줄 바꿈이 달라서 통일이 안되고 보기 힘들다”는 생각을 한 번쯤 해본 적이 있을 것이다.

물론 나도, 팀원도 통일된 컨벤션을 지키기에는 사람인지라 실수할 수 있고 어렵다

이럴 때 컨벤션을 통일할 수 있게 도와주는 도구가 ktlint이다.

 

ktlint는 Kotlin 코드를 위한 정적 코드 분석 및 자동 포매팅 도구다.
쉽게 말해, 코드를 자동으로 검사하고 스타일 규칙에 맞지 않는 부분을 손쉽게 고쳐주는 역할을 한다.
복잡한 설정 없이 바로 사용할 수 있으며, 공식 Kotlin 스타일 가이드와 Android 스타일 가이드에 기반해 동작한다.

 

ktlint 주요 특징

• 설정이 거의 필요 없다
  설치만 하면 바로 표준 규칙을 적용할 수 있다.
• 자동 포매팅 지원
  스타일 위반 부분을 자동으로 고쳐주기 때문에, 사소한 스타일 논쟁을 줄일 수 있다.
• .editorconfig 연동
  프로젝트마다 필요에 따라 규칙을 추가하거나 제외할 수 있다.
• 확장성
  커스텀 규칙을 만들어 팀만의 스타일을 적용할 수도 있다.
• 다양한 환경 통합
  Gradle, CLI, CI/CD 등 다양한 환경에서 쉽게 연동할 수 있다.

 

왜 ktlint를 써야 할까?

코드 스타일을 맞추는 것은 단순히 보기 좋으라는 이유도 있지만 가장 큰 이유는 코드의 일관성을 유지함으로써 협업이 쉬워진다.

코드 리뷰 하기도 편하며 리뷰 시간도 줄어든다.

• 코드 가독성 향상
  누구나 같은 규칙으로 코드를 작성하니, 읽고 이해하기가 훨씬 쉬워진다.
• 협업 효율 증가
  스타일 논쟁 대신 본질적인 코드 품질에 집중할 수 있다.
• 자동화의 힘
  pre-commit hook, CI 파이프라인 등과 연동해 스타일 위반을 사전에 차단할 수 있다.
• 레거시 코드에도 적용 가능
  기존 코드가 많아도 baseline 기능을 활용하면 점진적으로 스타일을 맞춰갈 수 있다.

---

1. 설치와 기본 사용

brew install ktlint

기본 명령어

• 코드 스타일 검사

ktlint
# 또는 jar 사용 시
java -jar ktlint-x.y.z.jar

• 자동 포매팅

ktlint -F
# 또는
java -jar ktlint-x.y.z.jar -F

 

• 특정 파일/디렉터리 검사

ktlint src/main/kotlin/ExamClass.kt
ktlint src/main/kotlin/

 

 

 

2. build.gradle 파일에 ktlint 플러그인을 추가

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

• 코드 검사: ./gradlew ktlintCheck
• 자동 포매팅: ./gradlew ktlintFormat

 

 

3. .editorconfig로 세부 설정

프로젝트 루트에 .editorconfig 파일을 두고, 필요에 따라 규칙을 켜고 끌 수 있다.

• .editorconfig 파일은 프로젝트 루트에 위치
• ktlint는 이 파일을 읽어 스타일 규칙을 적용

# 모든 Kotlin 파일에 적용
[*.{kt,kts}]
indent_size = 4
continuation_indent_size = 4
insert_final_newline = true
max_line_length = 120

# 특정 ktlint 규칙 끄기
ktlint_standard_no-wildcard-imports = disabled
ktlint_standard_import-ordering = disabled

 

 

자주 쓰는 옵션

1. indent_size: 들여 쓰기 크기
2. max_line_length: 한 줄 최대 길이
3. insert_final_newline: 파일 끝에 빈 줄 추가
4. ktlint_규칙명 = disabled: 특정 규칙 끄기

 

4. CI/CD에 연동하기

GitHub Actions, GitLab CI 등에서 ktlint를 자동으로 실행해 코드 품질을 관리할 수 있다.

name: ktlint
on: [pull_request, push]
jobs:
  ktlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
      - name: Run ktlint
        run: ./gradlew ktlintCheck

• PR마다 자동 검사: PR 생성 시 ktlint가 자동 실행되어 스타일 위반을 사전에 차단
• 실패 시 머지 불가: 스타일 위반이 있으면 빌드가 실패하므로, 코드 품질 유지에 효과적
• 리포트 파일 생성: build/reports/ktlint/ 경로에 리포트가 생성되어, 코드 품질 대시보드와 연동 가능

 

 

 

 

 

---

ktlint 도입 시 주의할 점

• 모든 스타일을 자동으로 고치지 못하는 경우도 있다
  일부 규칙은 수동으로 수정이 필요할 수 있다.
• 팀의 합의가 중요하다
  규칙이 팀의 개발 문화와 맞지 않는다면, .editorconfig나 커스텀 룰로 조정하는 것이 좋다.
• 기존 코드 일괄 적용은 신중하게
  대규모 프로젝트라면 baseline 기능을 적극 활용하는 것을 권장한다.

 

마무리

코딩 컨벤션은 코드의 일관성과 가독성을 보장하는 중요한 규칙이다.
요즘 이펙티브 코틀린 책을 읽고 있는데, 가독성은 개발자에게 있어 너무나도 중요하다는 것을 다시금 느끼고 있다.

Kotlin 공식 컨벤션을 따라 팀 내 협업과 유지보수를 원활하게 하며 코드 품질을 높여보고 싶다.
어떤 프로젝트든 팀원들과 초기에 컨벤션을 명확히 정하고 꾸준히 지키는 것이 무엇보다 중요하다는 생각으로 마무리하겠다.

 

 

참고 자료

Kotlin Coding Conventions	https://kotlinlang.org/docs/coding-conventions.html
ktlint GitHub	https://github.com/pinterest/ktlint
JetBrains Kotlin 스타일 가이드	https://github.com/JetBrains/kotlin-web-site/blob/master/pages/docs/reference/coding-conventions.md
이펙티브 코틀린