자바 코딩 컨벤션

지난 글에서 레거시를 안전망과 점진 교체로 현대화하는 전략을 다뤘다. 그렇게 새로 쓰거나 정리한 코드가 팀 안에서 제 값을 하려면, 여러 사람이 봐도 한 사람이 쓴 것처럼 읽혀야 한다. 코드는 작성되는 시간보다 읽히는 시간 이 압도적으로 길다. 그래서 코딩 컨벤션은 취향의 문제가 아니라, 읽는 사람의 인지 부하를 줄이는 공학적 결정이다. 이번 글에서는 자바의 명명·포매팅 관례를 짚고, 그것을 사람의 기억이 아니라 도구로 강제하는 방법까지 정리한다.

이름에 규칙이 있다

자바 커뮤니티는 오래전부터 요소별 표기법을 관례로 굳혔다. 덕분에 숙련된 개발자는 이름만 보고도 그것이 클래스인지 상수인지 지역 변수인지 즉시 안다. 이 예측 가능성이 컨벤션의 첫 번째 가치다.

public class OrderService {              // 클래스 · PascalCase
    private static final int MAX_RETRY = 3;  // 상수 · UPPER_SNAKE

    public BigDecimal calcTotal(Cart cart) { // 메서드 · camelCase
        int itemCount = cart.size();         // 변수 · camelCase
        return cart.sum();
    }
}

표기법 못지않게 중요한 것이 이름의 내용 이다. d, tmp, data 처럼 의미 없는 이름 대신 elapsedDays, pendingOrders 처럼 역할을 드러내는 이름을 쓴다. 좋은 이름은 주석을 대체한다. 불리언은 isActive, hasNext 처럼 질문형으로, 컬렉션은 복수형으로 짓는 관례도 널리 통용된다.

포매팅은 합의된 하나면 된다

들여쓰기를 스페이스로 할지 탭으로 할지, 중괄호를 어디에 둘지 같은 논쟁은 끝이 없다. 진실은 어느 쪽이 옳은지가 중요하지 않다 는 것이다. 팀이 하나를 정해 모두가 따르기만 하면 된다. 일관성 자체가 가독성이기 때문이다.

그래서 실무에서는 개인의 취향을 논쟁하는 대신, 검증된 스타일 가이드를 통째로 채택한다. 대표적으로 구글의 Java Style Guide나 AOSP 스타일이 있고, 이를 그대로 적용해 주는 google-java-format 같은 포매터가 존재한다. 스타일을 선택하는 순간, 개별 포매팅 논쟁은 사라진다.

사람이 아니라 도구가 지킨다

여기서 핵심 통찰이 나온다. 컨벤션 문서를 아무리 잘 써도, 사람이 리뷰에서 매번 눈으로 잡으려 하면 반드시 새어 나간다. 리뷰어의 에너지는 스타일이 아니라 로직에 쓰여야 한다. 그러니 일관성은 자동화 계층으로 강제 해야 한다.

// build.gradle — Spotless로 저장·빌드 시 자동 포맷
spotless {
    java {
        googleJavaFormat()      // 구글 스타일로 통일
        removeUnusedImports()
        trimTrailingWhitespace()
    }
}

각 계층의 역할은 다르다. .editorconfig 는 에디터 단에서 들여쓰기·인코딩·줄바꿈을 통일해 타이핑하는 순간 부터 어긋나지 않게 한다. Spotless 같은 포매터는 저장이나 빌드 시 코드를 정답 스타일로 자동 정렬한다. Checkstyle·PMD 는 명명 규칙 위반이나 금지 패턴을 빌드에서 검출해 차단한다. 마지막으로 CI 게이트 가 이 검사들을 파이프라인에 걸어, 규칙을 어긴 코드는 아예 머지되지 못하게 한다.

왼쪽 계층일수록 피드백이 빠르고 오른쪽일수록 최후의 방어선이다. 이 조합이 있으면 컨벤션은 “지키자고 다짐하는 것”에서 “어길 수 없는 것”으로 바뀐다.

컨벤션의 목적을 잊지 않기

한 가지 균형이 필요하다. 컨벤션은 가독성과 협업을 위한 수단이지 그 자체가 목적이 아니다. 규칙을 위한 규칙으로 변질돼 사소한 스타일에 리뷰 논쟁이 집중되면, 정작 중요한 설계·로직 검토가 뒤로 밀린다. 그래서 스타일은 도구에 위임해 논쟁 자체를 없애고, 사람은 도구가 잡지 못하는 의도와 설계 에 집중하는 것이 이상적인 분업이다.

정리

• 코드는 읽히는 시간이 훨씬 길다. 컨벤션은 취향이 아니라 읽는 사람의 인지 부하를 줄이는 공학적 결정이다.
• 자바는 요소별 표기법(PascalCase · camelCase · UPPER_SNAKE)이 관례로 굳어 있어, 이름만 봐도 종류를 알 수 있다. 이름의 내용도 역할을 드러내야 한다.
• 포매팅은 옳은 답이 아니라 하나로 합의된 답 이 중요하다. 검증된 스타일 가이드를 통째로 채택하면 논쟁이 사라진다.
• 일관성은 사람의 기억이 아니라 EditorConfig → Spotless → Checkstyle → CI 로 이어지는 자동화 계층으로 강제한다.

다음 글에서는 이 자동화 계층을 한 단계 더 밀고 나가, 스타일을 넘어 잠재적 버그와 코드 냄새까지 잡아내는 정적 분석 도구 를 다룬다.

---

지난 글: 레거시 코드 현대화 전략

다음 글: 정적 분석 도구 활용

읽어주셔서 감사합니다. 😊