처음으로 회사에서 제대로 된 프로젝트를 Git에 올리기 시작하면서, 나는 말 그대로 무한 피어리뷰의 늪에 빠졌다.
혼자 개발하거나 해커톤에서 빠르게 구현할 때는 서로의 커밋을 꼼꼼히 보거나 코드리뷰를 하는 경우가 거의 없다 보니, 나의 커밋 단위는 늘 크게 유지됐다.
기능 A를 어느 정도 완성하면, 다음 기능 B로 넘어가기 전에 일종의 백업용으로 커밋을 했기 때문이다.
즉, 나의 커밋은 협업을 위한 것이 아니라, 그저 나 자신을 위한 기록이었다.
협업 속 Git은 철저히 “남을 위한 도구”
하지만 회사에서의 커밋은 완전히 다르다.
커밋은 단순 백업을 넘어서 협업의 기반이자, 다른 개발자가 내 코드를 이해하도록 돕는 중요한 소통 수단이 된다.
동료들은 내 코드를 처음 본다.
심지어 프로젝트 전체를 clone하고 분석한 뒤 커밋을 읽는 것도 아니다.
그들은 커밋 메시지 제목 → 본문 → 코드 변경 순으로 읽으며 단서를 찾아간다.
즉, 커밋은 그들에게 있어 내 코드를 이해하기 위한 유일한 가이드라인이다.
그래서 나는 피어리뷰 늪에 빠지면서 깨달았다.
‘아… 지금까지의 내 커밋 방식은 협업에서 완전히 탈락이다.’
그렇다면 “이해하기 쉬운 커밋”은 무엇일까?
그걸 정의하려면 오히려 반대로 생각하면 쉽다.
상대가 절대 이해할 수 없는 커밋을 떠올려보면 된다.
이해하기 어려운 커밋의 3가지 특징
- 한 커밋에 너무 많은 것이 들어 있다
- 서로 다른 기능, 서로 다른 목적의 수정이 한데 섞여 있다.
- 읽는 사람은 이 커밋이 “무엇을 위한 것인지” 알기 어렵다.
- 커밋 간 순서가 뒤죽박죽이다
- A 작업 중간에 갑자기 생각난 B를 넣고, 그 뒤에 C가 끼어들고…
- 흐름이 없으니 읽는 사람은 작성자의 사고 과정을 추적하기 어렵다.
- 커밋 메시지가 나만 알아보게 쓰여 있다
- “fix bug”, “temp”, “작업함”, “update”…
- 메시지가 ‘왜 이런 커밋이 필요한지’ 설명하지 않는다.
돌아보면, 솔직히 말해 과거의 내 커밋은 이 모든 항목을 완벽히 충족하고 있었다…
이해하기 쉬운 커밋을 만드는 방법
그렇다면 하나씩 고치면 된다.
1. 커밋의 단위는 ‘작업의 의미’로 나눈다
A라는 기능을 구현하기 위해
a → b → c 순서의 작업이 필요하다고 해보자.
개발자인 나는 A라는 목적과 세부 단계들을 모두 알고 있지만,
이 커밋을 처음 보는 사람은 A가 무엇인지조차 모른다.
그래서 각 커밋에는 단 하나의 작업(a)만 들어가야 한다.
- “공통 Repository 인터페이스 추가”
- “MongoDB Repository가 인터페이스 구현하도록 수정”
- “DynamoDB 전용 Repository 추가”
이렇게 나누면 커밋 하나를 봐도 “이 커밋은 ○○를 위한 것”이라는 의미 전달이 명확해진다.
반면 a+b+c를 한 커밋에 넣으면
이유도 흐름도 목적도 전부 섞여버린다.
2. 커밋 순서 = 내가 실제로 코드를 작성한 순서
리뷰어는 커밋을 시간 순서대로 읽는다.
그 흐름은 곧 내 사고 과정의 흐름이 된다.
그런데 작업 중간에 갑자기 “아 맞다 이것도 고쳐야지” 하며
d 같은 다른 작업을 끼워 넣으면?
리뷰어는 자연스럽게 이 커밋이 왜 여기서 튀어나오는지 헷갈리게 된다.
따라서
생각난 수정이라도 작업을 끼워넣지 않고 별도 커밋으로 분리하는 것
(필요하다면 “chore: 누락된 validation 추가”처럼 명확하게)
이게 리뷰 난이도를 크게 낮춰준다.
3. 커밋 메시지는 “why / what / how” 구조로 쓴다
커밋 메세지는 내 커밋을 요약하는 부분이자, 상대가 코드를 읽기 전 읽게되는 부분이다.
따라서 아래와 같은 정보를 넣어주면 이해하기 쉽다.
why – 왜 이 커밋이 필요한가?
- 어떤 문제를 해결하는가
- 어떤 목적을 달성하는가
- 이 commit의 Goal이 무엇인가.
what – 목적을 위해 무엇을 했는가?
- 어떤 변화를 만들었는지
- 어떤 파일, 어떤 로직이 수정 혹은 추가되었는지
how – 기술적으로 어떻게 구현했는가?
- 어떤 방식, 어떤 패턴, 어떤 라이브러리를 사용했는지
- 특별한 이유가 있는 설계 선택이라면 반드시 여기에 포함
how는 상황에 따라 생략해도 된다.
단, 리뷰어가 “왜 이런 구현을 했지?” 하고 궁금할 만한 부분이 있다면 적어주는 것이 좋다.
실제 예시로 보는 좋은 커밋의 구조
상황:
기존 프로젝트는 MongoDB만 사용하도록 구조가 고정돼 있었고,
DB 전환이 어려운 문제가 있었다.
이를 해결하기 위해 브릿지 패턴을 도입해 구조를 유연하게 만들기로 했다.
그렇다면 커밋의 “why”는 다음과 같다.
특정 DB에 대한 종속성을 제거하고 쉽게 전환 가능한 구조를 만들기 위해
그리고 작업은 다음과 같이 나뉜다.
- 공통 Repository 인터페이스 정의
- 기존 MongoDB Repository가 인터페이스를 구현하도록 변경
- DynamoDB Repository 추가 후 공통 인터페이스 구현
이 각각이 하나의 커밋이 된다. 이 커밋들의 why는 모두 동일하겠다.
그리고 “how”에는
- 브릿지 패턴을 어떻게 적용했는지
- 어떤 인터페이스가 어떤 메서드를 갖는지
- 기존 구조와 어떻게 연결되는지
등의 내용을 적어준다.
정리하자면 핵심은 다음과 같다.
리뷰어가 커밋 메시지만 읽어도 “아 이런 코드가 나오겠구나” 하고 자연스럽게 예측 및 이해되도록 하는 것.
이렇게 커밋을 작성하면 다음과 같은 효과가 있다.
- 피어리뷰 시간이 줄어든다
- 동료들의 내가 작성한 코드에 대한 이해도가 올라간다
- 나 자신도 개발 단계·흐름을 더 명확하게 정리하면서 코드를 짤 수 있다
- 나중에 과거 코드를 다시 볼 때도 훨씬 빠르게 복기할 수 있다
커밋은 단순히 코드를 저장하는 도구가 아니다.
나의 사고 과정과 의도를 녹여, 미래의 나와 동료에게 ‘이해’를 전달하는 도구이다.