프로그래머는 동작하는 코드를 작성하는 것 이외에도 여러가지 문서화 작업을 한다.
그 중 커밋 메시지에 대해 이야기 해볼까 한다.
코드, 커밋 메세지, 주석도 모두 글쓰기다. 감성의 표현이 아닌 의사전달을 위한 글쓰기에서 첫번째로 중요한 것은 명확함이다. 글을 명확하게 쓰기 위한 도구로는 이미 육하원칙이 있다. 바퀴를 새로 만들지 않고, 육하원칙이라는 기존 도구를 사용하면 최소한의 명확함은 확보할 수 있다.
육하원칙을 적용하지만, git과 같은 버전관리 시스템에서 자동으로 처리해주는 요소들이 있다.
시스템에서 자동으로 처리해 주는 값은 시스템에게 맡기자.
우리는 자동으로 입력되지 않는 ‘왜’에 집중해야한다.
작성된지 1년 이상 된 코드를 읽어본 일이 있는가? 수년 이상 된 코드는(내가 작성한 코드라도) 무조건 남이 짠 코드로 보인다. 코드를 살펴보다 보면 이해가 안되는 부분이 보이기 마련인데, 이 때 커밋 메시지를 살펴보게 된다. 모든 코드에는 사연이 있기 때문이다(심지어 ‘그냥’이 이유더라도, 거기엔 ‘작업자 개인의 취향’이라는 사연이 들어있다).
그런데, 그 커밋 메시지에 ‘버그 수정’이나 ‘xxx를 yyy로 교체’같은 한 줄짜리 메시지가 남아있다면? 사연을 추측해야만 하고, 추측이 부담스럽다면 가급적 건드리지 않고 우회하는 방향을 선택하게 된다. 건드렸다 무슨 사달이 날지 모르니까. 어째서, 왜, 무엇때문에 그리 되었는지를 이해해야지만 엉뚱한일이 생기지 않는다.
코드의 이력도 이력서와 마찬가지로 스토리가 담겨있어야 한다. 그렇지 않으면 아무도 이해하지 못하는 태초의 미스테리가 늘어나는 제품이 된다. 거기에 하이럼의 법칙까지 추가되면, 미스테리는 지켜야 하는 규칙이 된다.
커밋 메시지에 관해 이야기 하는 다른 글에서도 비슷한 이야기를 한다. 좋은 git 커밋 메시지를 작성하기 위한 7가지 약속에는 7. 본문은 어떻게보다 무엇을, 왜에 맞춰 작성하기같은 항목이 있고, 스퀘어의 커밋 메세지 작성 방법에서도 코드를 읽을 고고학자들을 위해서 동기(motivation)을 기록해야 한다고 한다.
그렇다면 어떻게 기록해야 할까.
커밋 메시지에 최대한 구체적으로 적는것이 가장 좋다. 의사결정에 대한 배경, 과정, 결과가 다 있는 것이 이상적이겠지만, 현실적으로 모든 커밋을 그렇게 남기는 건 무리가 있다.
개인적으로는 이슈 관리 시스템이나 위키같은 문서화 시스템의 링크를 활용하는 방법을 좋아한다. 커밋은 불변(immutable)이라 뭔가를 더 추가하기 쉽지 않지만, 이슈 관리 시스템이나 위키는 맥락을 좀 더 자세히 쓰기 쉽고 나중에 수정도 가능하다. 물론 연동 시스템이 사라지거나 링크가 삭제되지 않도록 관리하는 것이 버전관리 만큼이나 중요한 일이 되지만, 장점을 생각하면 그 정도는 감수할 수 있다고 본다.
기억하자. 주석이나 커밋 메시지가 부실하면 부실한만큼 나중에 고통을 겪는것은 결국 내가 된다. (물론 퇴사하고 도망가면 상관 없…겠지만, 누군지 모를 후임자를 위해 기록하자)
내가 수년전에 적은 커밋 메시지나 이슈 내용을 보면 나도 할말은 없지만, 지금은 최대한 그러지 않으려고 노력한다는데서 위안을 얻..어본다. ( “)