이럴 때

몇 달 뒤의 내가 이 diff 를 보고 "왜 이랬지"라고 물을 것 같을 때. 기능을 끄거나 우회로 덮을 때. "꼭 ~하자", "나중에 다시 보자"를 쓰고 있을 때.

이렇게

• 방향 전환은 무엇 대신 무엇을 골랐고 왜인지 적는다.
• 장애는 증상·원인·확인 방법을 적고, 성능 수정에는 숫자를 적는다.
• 규범은 그 근거를 같이 적는다. 근거 없는 규범은 흉내가 되고 안 맞는 곳에도 적용된다.
• 기각한 안도 커밋으로 남긴다.

멈출 신호·예외

"나중에 다시 본다"를 문서에만 적고 싶어지면, 그 "나중에"를 스케줄러나 테스트에 건다. 버튼 여백 조정 같은 사소한 커밋에는 이유가 필요 없다.

설명

코드는 무엇을 했는지는 완벽하게 남기지만 왜 했는지는 남기지 않는다. 혼자 만든 코드라도 몇 달이 지나면 만든 사람도 잊는다. 방향을 바꾼 이유가 회고 중의 기억으로만 복구된 적이 있는데, 그건 운이었다. 「왜」의 마지막 보관소는 사람이고, 사람은 흩어진다. 접힌 프로젝트에서 남는 것은 레포뿐이다.

적는 자리도 중요하다. 교훈을 커밋 메시지에 박아 두었지만 그 문장은 그 레포를 다시 열 때만 읽혔고, 새 프로젝트에서 같은 실수를 막은 것은 문장이 아니라 테스트였다. 다시 봐야 할 교훈은 기계에 맡긴다.

반례

모든 커밋에 이유를 붙이면 소음이다. 그리고 "문서를 쓰자"는 결심은 잘 지켜지지 않는다. 그래서 최소 단위를 문서가 아니라 커밋 메시지 한 줄로 둔다.

판별법

"몇 달 뒤의 내가 이 diff 를 보고 「왜 이랬지」라고 물을까?"

물을 것 같으면 적는다. 커밋 메시지에는 한 일을 늘어놓지 말고 무엇이 되게 했는지를 적는다.