kwakseongjae 한 줄. 코드는 무엇을 하는지 말해주지만, 왜는 말해주지 않는다. 그 한 줄을 남긴다.
Why this mindset
진짜 프로그램은 코드가 아니라, 만든 사람 머릿속의 이해입니다 (Peter Naur, "Programming as Theory Building"). 그 이해를 남기지 않으면, 다음 사람 — 미래의 본인을 포함해서 — 은 같은 자리를 다시 헤맵니다. 무엇은 코드를 읽으면 알 수 있습니다. 하지만 왜는 그 자리에 없으면 영영 잃습니다. 그래서 우리가 남길 가치가 있는 단 한 가지는 왜입니다.
Instructions
모든 줄에 주석을 다는 게 아니다. 왜가 코드에서 안 보이는 자리에만, 한 줄 남긴다.
*커밋 메시지엔 무엇이 아니라 왜를 한 줄로.* diff가 무엇이 바뀌었나는 이미 말해준다. 메시지가 할 일은 왜 바꿨나. "update component"·"fix bug"·"refactor" 같은 건 둘 다 안 말해주는 가장 약한 메시지다.
- 약함:
fix login bug - 강함:
로그인 시 토큰 만료 직전 race condition 방지 — 재발급 후 요청이 더 빨리 도착하던 케이스
- 약함:
비자명한 결정 옆에만 왜 주석을. 자명한 코드 위엔 안 쓴다. 함수가 무엇을 하는지는 안 적는다 — 이름이 말해줘야 한다. 의례적 docstring("이 함수는 X를 한다")은 노이즈가 된다. 주석은 읽는 사람이 의아해할 자리에만.
우회·hack·이상해 보이는 코드엔 반드시 이유. *"왜 이래?"*가 다음 사람의 첫 반응일 자리엔, 그 질문이 나오기 전에 답을 둔다. 한 줄이면 충분하다.
// iOS Safari가 첫 렌더 직전에 폰트 사이즈를 잘못 계산해서, 16px 이상으로 강제- 이 한 줄이, 6개월 뒤 누군가가 "쓸데없어 보여서" 지우는 일을 막는다.
*다음 사람은 미래의 본인이다.* 본인이 한 달 뒤 자기 코드를 봤을 때 *"내가 왜 이렇게 했지?"*에 답이 있어야 한다. 코드는 짠 사람도 한 달이면 남이 된다. 미래의 자신에게 친절한 한 줄을 남긴다.
*PR 설명은 결정의 맥락을 담는다.* 어떤 옵션이 있었고, 왜 이걸 골랐는지. 코드만 보면 한 가지 정답처럼 보이지만, 거기엔 보통 고른 길과 고르지 않은 길이 있다. 후자를 한 줄 남기면 — 다음 사람이 같은 길을 다시 의심하느라 쓰는 시간을 줄여준다.
Examples
커밋 메시지 — 무엇이 아니라 왜:
- 약함:
add caching - 강함:
검색 결과 캐싱 추가 — 동일 키워드를 5분 내 재검색하는 사용자 패턴이 GA에서 30% 관찰됨
hack에 한 줄:
// Firefox는 input event를 paste 직후 두 번 발생시킴 (2024 기준).
// 100ms debounce로 중복 처리 방지. Firefox가 고치면 제거 가능.
const debounced = debounce(handleInput, 100);
의례적 주석은 안 씀:
// 안 씀 — 이름이 다 말해주는데 노이즈
// Validates an email address
function isValidEmail(email: string): boolean { ... }
PR 설명 — 고른 길과 안 고른 길:
"장바구니 동기화를 서버 단일 소스 방식으로 변경. 옵션이었던 클라이언트 마지막 쓰기 우선은, 다중 탭에서 충돌 빈도가 측정 단계에서 너무 높아 제외. 트레이드오프 — 오프라인 동기화는 일단 비활성. 추후 별도 이슈로."
Pitfalls
- 무엇만 적힌 커밋 메시지 (
update,fix,refactor) → 6개월 뒤 누구도 왜를 모름 - 자명한 코드 위에 의례적 주석 → 노이즈만 늘고 진짜 왜는 묻힘
- 이상한 우회 코드를 설명 없이 남기기 → 다음 사람이 두려워서 못 만짐 / 모르고 지움
- "코드가 다 말해줘야지" 극단주의 — 왜는 코드가 절대로 말하지 않는다
- 주석을 너무 길게 → 다음 사람이 안 읽음. 한 줄이 정답
- 왜가 코드와 함께 갱신 안 됨 → 거짓말하는 주석. 코드가 바뀌면 왜도 같이.
코드는 결과물이고, 우리가 진짜 남기는 건 이해다. 그 이해를 다음 사람 손에 쥐어주는 한 줄이, 코드베이스를 유산이 아니라 길로 만든다.