1. 왜 규칙이 필요한가?
여러 명이 하나의 프로젝트를 진행하다 보면, 각자의 코딩 스타일과 선호하는 단어가 다르기 마련이다.
이번 프로젝트에서는 "마치 한 사람이 짠 코드처럼 보이게 만드는 것" 을 목표로 삼았고, 이를 위해 개발 시작 전 팀원들과 함께 규칙들을 정리했다.
2. 용어 사전: 언어의 통일
단순히 변수명을 맞추는 것을 넘어, 도메인의 핵심 개념을 팀 전체가 동일하게 이해하고 사용하는 과정이다.
2.1. 필드명 규칙
| 범주 | 용어 | 필드명 (camelCase) | 설명 |
|---|---|---|---|
| 식별자 | ID | ~Id (예: userId) | 모든 PK 및 FK 뒤에 붙임 |
| 이름/제목 | Name / Title | name, title | 사람/상품은 name, 공지/노트는 title |
| 금액/가격 | Price / Amount (BigDecimal) | price, totalAmount | 개당 단가는 price, 합산은 amount |
| 수량 | Stock / Quantity | totalStock, quantity | 재고 총량은 stock, 주문 수량은 quantity |
| 일시 | At | ~At (예: createdAt) | DateTime 필드 뒤에는 반드시 At |
| 날짜 | Date | ~Date (예: birthDate) | 시간 없이 날짜만 관리할 때는 Date |
| 여부 | Is / Has | is~ (예: isDeleted) | Boolean 필드는 is 또는 has로 시작 |
2.2. 행위(Action) 메서드명 규칙
메서드명만 보고도 어떤 역할인지 바로 알 수 있도록 접두사를 통일했다.
| 동작 | 메서드명 | 예시 |
|---|---|---|
| 생성 | create | createUser, createOrder |
| 조회 (단건) | findById | findUserById, findOrderById |
| 조회 (목록) | findAll | findAllOrders, findAllOrdersByUserId |
| 조회 (조건) | findBy{조건명} | findByEmail, findByStatus |
| 수정 | update | updateUser, updateInventory |
| 삭제 | delete | deleteUser, deleteLike |
| 검증 | validate | validateCredential, validatePaymentAmount |
| 처리 | process | processPayment, processRefund |
| 발행 | publish | publishStockRestoreEvent |
| 승인 / 취소 / 등록 | approve / cancel / add | approveRefund, cancelOrder, addLike |
3. 구글 자바 스타일 가이드와 Checkstyle 적용
용어 사전이 '내용(의미)' 을 규정한다면, Checkstyle은 '형태(형식)' 를 강제한다.
3.1. 왜 구글 자바 스타일인가?
구글 자바 스타일 가이드는 전 세계적으로 검증된 코드 표준이다. 들여쓰기 2칸, 중괄호 위치 등 명확한 기준을 팀 전체가 동일하게 적용할 수 있다.
3.2. Checkstyle 도입 효과
- 자동 코드 검토: 들여쓰기, 중괄호 위치, 미사용
import등을 자동으로 검사한다. - 빌드 안정성: 규칙 위반 시 빌드 자체가 실패하도록 설정하여, 낮은 품질의 코드가 저장소에 유입되는 것을 방지한다.
3.3. build.gradle 설정 예시
plugins {
id 'checkstyle'
}
checkstyle {
toolVersion = '10.12.1'
configFile = file("config/checkstyle/google_checks.xml")
}
tasks.withType(Checkstyle).configureEach {
reports {
html.required = true
}
}
google_checks.xml파일은 Checkstyle 공식 GitHub에서 받아 프로젝트 내config/checkstyle/경로에 위치시키면 된다.
4. 담당 도메인 상세 규칙
담당 도메인은 Product(상품) 과 Drop(드랍) 이다.
4.1. Product
상품의 생명주기와 노출 기준을 정의한다.
- 등록 조건:
seller역할 계정만 등록 가능하며, 이름·가격·카테고리·대표 이미지(1장 이상)가 필수다. - 상태 흐름:
HIDDEN→READY→ON_SALE→OUT_OF_STOCK순으로 전이되며, 드랍 시간 미입력 시HIDDEN상태를 유지한다. - 수정 제한: 드랍이 예약 중이거나 판매 중인 경우, 상품명·가격·옵션 정보는 수정할 수 없다.
- 목록 조회: 상태별 필터링과
최신순 / 높은 가격 순 / 낮은 가격 순 / 드랍 임박 순정렬을 지원한다. - 상세 조회: 상단에는 상품 핵심 정보(가격, 재고, 이미지, 드랍 정보)를, 하단에는 상품 설명·사양·배송·환불 정책을 노출한다.
- 이미지: 최대 5장까지 등록 가능하며, 드랍 시작 24시간 전부터 목록에 노출되나 구매 버튼은 비활성화 상태다.
4.2. Drop
한정 수량 판매 이벤트의 진행 조건과 재고 정합성을 정의한다.
- 시간 조건:
startAt은 과거 시간 불가,endAt은 반드시startAt이후여야 한다. - 수량 제한: 드랍 수량(
totalStock)은 실제 상품 재고를 초과할 수 없으며, 1인당 구매 가능 수량을 별도로 제한한다. - 상태 흐름: 시작 시간 도달 시 자동으로
ACTIVE로 전환되며, 수량 소진 또는 종료 시간 초과 시 즉시FINISHED로 전환된다. - 변경 제한:
ACTIVE상태에서는totalStock과startAt변경이 불가하며, 주문이 존재하는 드랍은 삭제할 수 없다. - 선착순 Queue: 선착순 드랍 활성화 시
Queue도메인을 통과한 사용자에게만 구매 권한이 부여되며, 권한은 5분간 유효하다. - 재고 복구: 결제 실패 또는 주문 취소 시, 차감된 드랍 재고는 즉시 자동으로 복구된다.
5. 오늘을 마치며
규칙을 정하는 과정은 처음엔 번거롭고 시간이 걸리는 작업처럼 느껴졌다. 하지만 이 과정을 생략했다면 나중에 수백 개의 클래스를 수정해야 하는 기술 부채로 돌아왔을 것이다.
특히 용어 사전을 만들면서, 팀원마다 같은 개념을 서로 다른 단어로 부르고 있었다는 걸 처음 인지했다. 코드를 짜기도 전에 이런 충돌을 미리 해소할 수 있었다는 점에서, 컨벤션 수립은 단순한 형식 맞추기가 아니라 팀이 같은 언어로 소통하기 위한 필수 과정임을 실감했다.
"협업은 약속에서 시작된다"
