커밋 메세지 본문은 "어떻게"보다 "무엇을", "왜"에 맞춰 작성하기

 커밋 메세지 작성의 중요성

---

개발자의 개발 능력 못지 않게, 협업 능력이 중요하다는 것은 이제 모든 개발자들이 공감하는 부분 일 것입니다. 좋은 협력이란 핵심을 딱딱 짚는 좋은 커뮤니케이션 능력과 부드럽고 협조적인 대화스킬도 있겠지만, 커밋 메세지 작성의 견고함도 포함된다고 생각합니다. 코드로 승부하는 IT 세계에서, 다른 동료들과 협업할 때 나의 작업물의 의도를 커밋메세지로 잘 드러내는 것 만큼, 다른 동료들의 업무 향상성을 높이는 길이 없습니다.

 

 좋은 커밋 메세지를 작성하기 위한 여러가지 가이드라인이 있습니다. 대표적으로 Chris Beams의 How to Write a Git Commit Message 글에서 7가지를 소개하고 있는데, 그 중에 커밋 메세지의 본문은 어떻게보다 무엇을, 왜에 맞춰 작성하라는 것에 관련되어서 알아보고자 합니다.

 

 

좋은 커밋 메세지 자세히 확인해보기

---

 오늘은 전 NHN 개발자 김은호님의 강의 커밋 메세지와 블로그 글을 소개하고 메세지를 한번 엿보겠습니다.

 

 김은호 개발자님이 2017년 즈음, NHN 블로그에 좋은 git 커밋 메시지를 작성하기 위한 7가지 약속 을 올려주셨고, 얼마전에는 패스트캠퍼스에 강의까지 찍어주시면서 깃 메세지를 배울 기회가 생겼습니다. 먼저 해당 글에서 소개되어 있는 좋은 메세지의 예시 입니다.

 

 

해당 예시는 다음 링크에서 코드의 변경과 함께 자세히 살펴볼 수 있습니다. ( 링크 )

 

Remove the 'state' and 'exceptmask' from serialize.h's stream implementations,
as well as related methods.

 

무엇을 변경했는지 명시합니다.

 

 

 

As exceptmask always included 'failbit', and setstate was always called with
bits = failbit, all it did was immediately raise an exception. Get rid of
those variables, and replace the setstate with direct exception throwing
(which also removes some dead code).

 

왜 변경했는지 명시합니다.

 

 

 

As a result, good() is never reached after a failure (there are only 2
calls, one of which is in tests), and can just be replaced by !eof().

 

앞의 변경으로 인해, "무엇"이 또 변경되었고 "왜" 변경했는지 설명합니다.

 

 

fail(), clear(n) and exceptions() are just never called. Delete them.

 

 

 무엇을 변경했고, 왜 변경했는지를 작성하였습니다. 그리고 그 여파로 다른 코드들에 어떤 영향을 주었는지, 따라서 어떻게 수정되었는지까지도 담겨져 있습니다. 모든 코드 변경사항을 빠짐없이 친절하게 알려주었으므로 한번에 이해가 되는 좋은 커밋 메세지입니다.

 

 

 결국, 궁극적으로 코드를 "왜" 변경했는지를 작성해야 합니다. 무엇이 추가되었고, 무엇이 삭제되었는지는 이미 커멋된 코드를 보면 알 수 있습니다. 내 옆자리 직원들이 내가 작성한 코드와 커밋 메세지를 보고 빠르게 이해하도록 한다면 업무 생산성이 향상 될 것입니다.

 

 

아래 내용은, 다른 블로그에서 참조했습니다.

 

처음에 변경한 이유를 명확히 하는 데 집중하십시오.

1. 변경 전의 작동 방식(그리고 무엇이 잘못되었는지),
2. 현재 작동하는 방식,
3. 당신이 선택한 방식으로 해결하기로 결정한 이유

-https://cbea.ms/git-commit/

 

 

김은호님 강의 커밋 메세지 확인해보기

---

이 때, 다른 커밋이나 링크를 참조하여 이해를 한층 더 도울 수 있는 방법이 있으므로 적절히 활용하도록 합니다.

 

실제 실무는 아니지만, 김은호님이 패스트캠퍼스 프로젝트를 진행하면서 작성하셨던 메시지를 살펴보도록 하겠습니다.

 

예제 프로젝트이므로 커밋 단위가 크거나 메세지가 상세하지 않은 것은 감안했습니다.

 

링크는 다음과 같습니다 ( fastcampus-project-board )

 

 

 

 

처음 초기화를 하고나서 어떤 의존성들을 추가했는지 적음

 

 

 

revert도 왜 했는지 이유를 적어줍니다. 메시지가 없었다면 이유를 모르겠지만 간단명료하게 이해 가능

 

 

 

추후에 업데이트 할 수 있다는 표현이 좋음. 미래에 추가 작업이 있을 것을 알려줌

 

 

 

TODO 를 사용해서 앞으로 처리할 내용이 있다는 것을 암시하는 것이 좋음

JpaConfig클래스에 `JpaConfig`처럼 `` 를 추가

 

 

테스트라 가능한 이야기지만, 이대로는 실패한다고 아예 실패 케이스라고 알림

 

 

 

특정 기술을 사용했음을 알리고 관련된 링크로 이해를 도움

 

 

사소한 한 줄 수정도 이유를 적음

 

 

 

 

왜, 무엇을 어떻게 변경했는지 있음. 또한 그 이외의 내용도 언급함. 왜 @DateTimeFormat을 사용했는지도 적었으면 좋았을 듯. 

 

 

 

data rest를 이용해 테스트한 이유를 적음, 또한 @Transactional을 적용한 이유도 명시

 

 

 

실패 테스트를 그대로 커밋하는데, 배포 자동화에 악영향을 주지 않기 위해 @Disabled 처리 및 해당 내용을 명시.이렇게 하면 실패 테스트 커밋에 대한 부담감이 줄고, 꼭 무조건 테스트를 100% 성공하고 커밋해야 한다는 강박증도 줄어듬

 

 

 

이전에 커밋한 고유번호 7자리를 활용하여 참고할 수 있도록 첨부, 읽는 입장에서 해당 커밋을 참고하면 되기 때문에 더이상 커밋 메세지를 작성하지 않아도 됌

 

 

 

최신 설정을 활용했던 내용을 적어주고, 관련한 링크까지 추가함.

 

 

부트스트랩을 사용했다는 내용만 간단하게 적고 관련된 링크를 첨부함

 

 

 

 

초기 테스트 골격을 잡을 때 각 테스트메서드마다 커밋이 아니라 한꺼번에 테스트를 커밋하고 짧게 내용을 적음

 

 

페이징 기능을 추가하는데, 어떤 방식으로 설계하였는지도 함께 적음

 

 

뷰 템플릿이 지저분할 수밖에 없었던 이유를 적음, 또한 카운트 쿼리에 대해서도 설명

 

 

서버에 정렬 기능이 어떻게 구현되어 있는지 간단하게 짚고 넣어감

 

 

 

잘못된 설계를 왜 고치게 되었는지, 이후에는 어떻게 고쳤는지 설명

 

 

검색 기능을 구현했다는 내용 이외에 서버와 뷰가 어떻게 작용하는지 설명, 코드가 "왜" 그렇게 짜여졌는지 설명

 

 

코드에 대한 설명도 좋지만, 위의 메세지와 같이 해당 페이지가 어떤 페이지인지를 알려 줄 수도 있음

 

 

 

기존 게시판 페이지와 비교하면서 추가된 내역을 상세하게 정리함

 

 

 

Serializable 설정을 Jackson 으로 변경하는 내용으로 별 다른 이유가 없다면 그냥 그대로 적음

 

 

 

단순히 의존성을 추가했다는 것에서 끝이 아니라, 누락이 되었다고 말하며 추가된 이유를 적음

 

 

 

왜 팩토리 메소드가 추가되었는지 이유들을 나열

 

 

단순히 타임리프 태그로 처리하도록 변경했다는 것 이외에 리소스 접근에 안전하다는 이유를 적음