커밋 주석은 왜라는 질문에 답할 수 있어야 한다

개발자들의 일상 업무 중 하나는 소스 코드를 작성하고 버전 관리 도구를 사용해 “커밋”하는 일일 것이다. 소스 저장소라고 하는 신성한 영역에 내가 공들여 만든 소스 한 조각을 추가함으로써 IT 시스템을 진화시키는 것이다. 마치 매트릭스 3편에서 네오가 자신의 몸을 데우스 엑스 마키나에게 맡겨 가상의 소스를 건네주는 것처럼.

그런데 버전 관리 도구들은 커밋할 때 주석(개발자의 의견)을 입력할 수 있게 돼 있는데(아래 그림) 개발자 대부분이 이를 허투로 넘긴다. 이 커밋 주석이라는 녀석을 공들여 작성해야 한다는 것이 프로젝트할 때마다 내가 개발자들에게 언급하는 부분인데 특히 커밋 주석은 왜라는 질문에 답할 수 있어야 한다.

Eclipse Git 커밋 대화창
Eclipse Git 커밋 대화창

예를 들어 어떤 고객 요구사항에 대해 개발한 것인지, 어떤 버그를 수정하기 위해 작업한 것인지, 개인적으로 수정한 경우 그 주관적인 판단의 이유가 무엇인지 등등이다.

공공 프로젝트의 정보시스템 감리를 받아보면 빠지지 않고 나오는 것이 요구사항 추적표다. 원청자(고객)의 요구사항들이 시스템에 어떻게 녹아들어갔나를 표로 만들어 요구사항 충족도가 100%가 됐는지를 확인할 수 있게 하는 것이다. 커밋 주석을 통해 이러한 포멀한 절차에 일조하는 것도 있겠지만 보다 직접적으로는 소스 코드 관리의 품질을 담보할 수 있는 수단도 되기 때문에 필요하다.

버전 관리 도구는 인간의 기억력 한계를 극복하는 데 크나큰 공헌을 한다. 과거 내가 무엇을 어떻게 했는지 되살릴 수 있는 타임머신과 같은 것이다. 그런데 이때 타임머신이 있더라도 내가 역사를 전혀 모른다든가 과거에 어느 시점으로 돌아가야 하는지 모른다면 돼지 목에 진주 목걸이와 마찬가지가 아니겠는가? 사람의 기억력이 한계가 있기 때문에 바로 이 지점에서 커밋 주석이 큰 역할을 할 수 있다.

소스 코드를 아무리 시간별로 어떤 내용이었는지 일일이 확인할 수 있더라도 “왜 그랬는가!”를 밝히는 짧은 주석이 훨씬 효용성이 크다. 간혹 주석을 작성하더라도 변경 내용 자체를 주석으로 작성하는 경우가 있는데 그건 의미가 없다. 버전 비교를 하면 어떤 내용을 변경했는지 알 수 있으므로 그건 결국 동어 반복에 불과하다.

예를 들어 “if 조건 추가”라는 주석을 보자. 이건 변경 내용 자체를 말하는 것이다. 왜 그랬는지 전혀 나타나있지 않다. 이유가 없으므로 사실상 주석을 통해 변경 내용을 이해할 수 없을 것이다. 하지만 “null 검사가 없으면 뒷부분에서 NullPointerException 발생”이라든가 “버그 #23번 참고”와 같이 쓴다면 소스에 대해 훨씬 쉽고 간단히 이해할 수 있다. 하다못해 “회의 들어가기 위해 일단 커밋”이라고 써도 내가 볼 때는 훌륭한 주석이라고 생각한다.

존재하는 모든 것에는 이유가 있다고 하는 라이프니츠의 사상처럼 소스 코드 역시 왜 그런 소스가 들어간 것인지 이유가 있어야 한다. 이제부터 커밋 주석을 작성할 때는 “내가 왜 이런 작업을 했지?”라는 질문에 대한 대답을 내용으로 작성해보도록 하자.

커밋 주석은 왜라는 질문에 답할 수 있어야 한다”에 대한 의견

의견 있으시면 냉큼 작성해주세요~