DR-0017: 코드의 주석은 영어, 커밋은 Conventional Commits에 한국어 본문
배경
MVP 코딩을 시작하기 전에 코딩 가이드를 만들기로 했다(메인테이너: “코딩 인벤션을 정의해주세요. 내가 개발할 때는 코딩가이드 문서같은게 쥐여졌었는데 있는게 좋을까요?”). 가이드의 대부분은 도구의 설정과 설계에서 따라 나오지만, 둘은 메인테이너가 정해야 했다: 코드 주석을 어느 말로 쓰는가, 커밋 메시지를 어떤 꼴로 쓰는가. 문서(docs/ · atelier/)는 한국어이고, 지금까지의 커밋은 한국어 자유 형식이다.
결정 기준
- 사용자와 컨트리뷰터가 한국어 밖에도 있다(화면의 기본 언어는 영어 → R-NFR-04)
- 코드를 주로 Claude가 쓰고 메인테이너가 리뷰한다
- 커밋 기록에서 코드의 변경을 가려 보고, 나중에 릴리스 노트를 만들 수 있다
검토한 대안
| 물음 | 대안 | 고른 것 |
|---|---|---|
| 주석의 말 | 영어 / 한국어 | 영어 |
| 커밋 메시지 | Conventional Commits + 한국어 본문 / Conventional Commits + 영어 / 지금처럼 자유 형식 | Conventional Commits + 한국어 본문 |
- 주석을 한국어로 쓰면 설계 문서와 같은 말이라 이어 읽기 쉽지만, 한국어 밖의 컨트리뷰터에게 벽이 된다. 영어로 쓰고, 설계와는 요구사항 ID와 ADR 번호로 잇는다.
- 커밋을 영어로 쓰면 오픈소스의 흔한 관례지만, 메인테이너가 기록을 읽는 말은 한국어다. 머리의 종류(
feat·fix…)와 범위만 정해진 영어로 두면 도구와 사람 모두 가려 볼 수 있다.
결정
메인테이너가 고르는 창에서 정했다(2026-11-01, 셋 모두 Claude의 추천).
- 코드 주석과 개발자에게만 보이는 문자열(예외 메시지, 로그)은 영어. 식별자도 영어다. 설계 문서는 한국어 그대로다.
- 커밋 메시지는 Conventional Commits 꼴의 머리(
feat(core): …)에 한국어 본문. 문서만 바꾼 커밋은docs:를 붙이거나 지금처럼 쓴다. - 코딩 가이드는
docs/07-coding-guide에 둔다. 도구에 맡기는 규칙은 그 도구의 설정까지 가이드에 정의한다(메인테이너: “도구에 위탁하는 부분이 있다면 그 도구에 대한 정의도 있어야겠네요”).
규칙의 세부는 코딩 가이드에 있다.
결과
- 좋아지는 점: 코드는 누구나 읽고, 기록은 메인테이너가 읽기 쉽다. 커밋의 종류로 코드 변경을 가려 볼 수 있다.
- 감수하는 점: 주석과 설계 문서의 말이 다르다. 그래서 개념의 이름은 용어집의 “영어” · “코드 이름” 칸으로 맞춘다.