콘텐츠로 이동

린트와 코딩 스타일

서버 코드는 세 가지 도구가 겹치지 않게 나눠 검사해요. 서식은 Spotless가 고쳐 쓰고, 이름과 관례는 Checkstyle이, 결함 패턴은 SpotBugs가 봐요. jOOQ가 생성한 코드는 셋 모두에서 빼요.

서버 코드를 바꾸면 server/에서 테스트를 돌려요. cowork AGENTS.md가 정한 검사예요.

터미널 창
./gradlew test integrationTest
명령 하는 일
./gradlew test integration 태그가 없는 테스트
./gradlew integrationTest integration 태그가 붙은 테스트
./gradlew spotlessApply 서식을 고쳐 써요
./gradlew spotlessCheck 서식이 맞는지만 확인해요
./gradlew checkstyleMain Checkstyle 검사
./gradlew spotbugsMain SpotBugs 검사
./gradlew check 위 검사와 테스트를 모두 돌려요

check는 Gradle 플러그인들이 각자의 검사를 걸어 두는 작업이고, build.gradle이 여기에 integrationTest를 더해요.

src 아래 모든 Java 파일에 palantir-java-format을 적용하고, 안 쓰는 import를 지우고, 애너테이션 자리를 맞춰요.

server/build.gradle
spotless {
java {
target fileTree('src') { include '**/*.java' }
palantirJavaFormat()
removeUnusedImports()
formatAnnotations()
}
}

Checkstyle 13.8.0을 쓰고, 경고를 하나도 허용하지 않아요(maxWarnings = 0). 규칙은 server/config/checkstyle/checkstyle.xml에 있어요.

묶음 검사
파일 탭 문자 금지, 파일 끝 줄바꿈
import * import, 겹친 import, 안 쓰는 import, 금지된 import
이름 패키지·타입·메서드·필드·인자·지역 변수·상수 이름
결함 유발 패턴 equals와 hashCode 짝, 문자열을 ==로 비교, switch의 default 누락, 다음 case로 흘러내림, 빈 블록과 빈 catch, 금지된 포괄 catch
단순화 불필요하게 복잡한 불리언 식과 반환
구조 파일 하나에 최상위 클래스 하나, 파일 이름과 타입 이름 일치, 제어자 순서, 불필요한 제어자

테스트 코드는 메서드와 상수 이름에 한국어 문장을 쓸 수 있게 이름 규칙에서 빠져요(suppressions.xml).

컴파일한 코드에서 결함 패턴을 찾고 HTML·XML 보고서를 남겨요. 일부러 제외한 것은 server/config/spotbugs/exclude.xml에 사유와 함께 적어요. 생성한 jOOQ 패키지, 생성자 주입으로 협력 객체를 보관하는 패턴(EI_EXPOSE_REP2), 테스트에서만 일부러 하는 몇 가지가 여기에 있어요. 제외를 더할 때는 사유를 주석으로 남겨요.

검사기가 다 막지 못하지만 지키는 것이에요.

  • 역할을 이름으로 드러내요: …Controller, …Service, …Query, …Repository, …Requests, …Views, …ErrorCode. 저장소와 조회 구현에는 Jooq…처럼 기술 이름을 붙여요.
  • 의존성은 생성자로 주입해요. 필드와 인자 이름은 선언 타입의 lowerCamelCase로 써요.
  • 없을 수 있는 조회는 find…와 Optional, 반드시 있어야 하는 조회는 get…과 예외를 써요.
  • 불변 값과 전달 타입은 record로 쓰고, 접근자는 name() 형식이에요.
  • HTTP 요청·응답 타입은 피처의 …Requests·…Views에 묶고, 모듈 계약 전용 타입은 …Facade 안의 Param·Result에 묶어요.
  • 현재 시각은 주입한 Clock에서 받아요.
  • 예외를 빈 catch나 포괄 catch로 삼키지 않아요. 같은 실패를 여러 층에서 겹쳐 기록하지 않아요.
  • 테스트는 업무 불변식, 원자성, 중복 명령, 권한처럼 밖에서 관찰할 수 있는 결과를 검증해요.