[개발 도서] 개발자는 글을 못 쓴다고요? - 커밋 메시지 작성하기

 

https://product.kyobobook.co.kr/detail/S000218400404

개발자는 글을 못 쓴다고요? | 전정은 - 교보문고

 

p.12

- 훌륭한 개발자가 되려면 뛰어난 소프트웨어 개발 능력뿐만 아니라 원활한 소통 능력도 필요합니다.

 

p.29

- 글 잘 쓰는 개발자가 되려면 쓰지 않는 습관과 코드로 소통한다는 생각의 굴레에서 벗어나야 합니다.

- 우선 단번에 좋은 글을 써내겠다는 희망을 버리세요. 그런 생각을 하면 오히려 글쓰기가 힘들고 어렵게 느껴져 시작하기 힘듭니다.

 

p.44

- 내가 커밋한 코드를 왜 커밋했는지, 왜 그렇게 구현했는지 시간이 어느 정도 지나면 나도, 또 내 코드를 보는 이도 알 수 없습니다. 기록이 없다면 말입니다. 시간이 지난 후에도 기록이 유의미하도록 기록을 잘 쓰고 잘 남겨야 합니다.

- 기록을 잘 찾을 수도 있어야 합니다.

- 커밋 메시지를 작성할때는 검색도 고려해야 합니다. 

 

p.46

- 커밋 메시지 제목(이하 제목)이 너무 길다면 그 커밋에는 너무 많은 걸 담았다 생각하고 커밋을 분리해야 합니다.

- 한 커밋에 담기는 파일들은 전부 동일한 목적을 달성하는 변경 사항을 담은 파일들이어야 합니다.

- 커밋 범위를 잘 구성하면 제목을 수월하게 쓸 수 있는것은 물론, 혹여나 롤백rollback해야 할 상황이 발생했을 때 도움이 됩니다.

- 깃헙에서 제목과 본문을 구분해 표시하는 커밋 방법은 있습니다. (첫 줄 입력 후 따옴표를 닫지 않고 엔터를 치면 줄바꿈이 됩니다.) 

git commit -m "feat: 메인 페이지 UI 개선 --> <제목>
<본문 내용>
- 헤더 디자인 수정
- 푸터 링크 추가"

 

p.49

- 리뷰어 입장에서 개발자가 무엇을 달성하려고 코드를 작성했는지 알고 리뷰하는것과 전혀 모른 채 리뷰하는 것은 다르지 않을까요? 목적을 확실하게 알면 커밋된 코드가 실제로 그 목적을 달성하는지 여부를 판단하는 데 도움을 얻을 수도 있습니다.

 

p.50

- 많은 오픈소스 저장소에는 CONTRIBUTING.md 파일이 있습니다. 파일을 보면 지켜야 할 코딩 스타일과 더불어 커밋이나 풀 리퀘스트를 올리는 방법 등을 안내합니다. 

- 커밋 메시지 제목이나 풀 리퀘스트 제목을 영어로 쓸 때는 동상 명령형으로 시작하는 것을 추천합니다. 

- '하다'라는 동작을 '해라', '하게' 등의 형태로 표현하는 것이 동사 명령형입니다.

(예시. 커밋메세지: added an object(x), add an object(0))

 

p.54

- 커밋 메세지의 목적어를 꾸미는 다양한 방식

공식 1: 해라 (어떤) 무엇을
제목  : Add (absent) students

공식 2: 해라 무엇을 (어떤)
제목  : Add students (who are not listed in the roll)

 

- 커밋 메세지의 언제라는 정보를 추가할 수 있는 방식

공식 1: 2주마다 학생을 출석 시스템에 등록하는 코드 커밋
제목  : Add students to the attendance system every two weeks

공식 2: 출석 시스템이 준비 상태가 되면 학생을 추가하는 코드 커밋
제목  : Add students when the attendance system is ready

 

p.56

- 제목에 쓸 만한 동사

기능 분류: 동사
----------------------------------------------------------------------------------
추가    : add, create, generate, include, introduce, issue, post, put, save, store
----------------------------------------------------------------------------------
변경    : bump,change,configure,edit,fix,modify,rename,replace,set,update,upgrade
----------------------------------------------------------------------------------
삭제    : cancel, delete, eject, eliminate, erase, exclude, hide, remove, reset
----------------------------------------------------------------------------------
그 외   : alert,align,allocate,allow,alternate,delimit,display,divide,draw,enable,
		 enter,fix,follow,free,get,handle,initialize,improve,notify,order,process,
         provide,read,refactor,retrieve,return,rewrite,search,separate,show,sum,stop
         strip,support,terminate,use,watch,wait,write
----------------------------------------------------------------------------------

 

p.57

- 커밋한 후 수개월 혹은 수년이 지난 후에도 이 커밋이 무엇을 위해 커밋된 것인지 바로 파악할 수 있도록 상세하게 작성하세요.

- 내가 어떤 코드를 추가했고 바꿨는지는 git diff로, 코드 변경 전후를 비교하면 바로 알 수 있습니다. 

- 커밋에 담긴 코드를 언급하는 대신 코드가 수행하는. 기능 관점이나 내가 한 작업을 설명하는 제목을 작성하세요.

    * 내가 추가한 코드가 하는일. (ex. "Find students by name" )

    * 내가 추가한 코드 때문에 뭘 할 수 있게 됐는가? (ex. "Enable finding students by name")

        * 이전에는 이름으로 학생을 찾을 수 없었는데 내가 올린 커밋이 병합되면 가능해진다는 것을 알림.

    * 내가 코드를 추가해서 전과 뭐가 달라졌는가? (ex. "Add the name filter for searching students")

        * 학생을 조회하는 기능은 이미 있었으나, 기존 기능에 부가 기능을 추가한 것을 알림.

 

p.62

- 커밋 제목을 줄이려고 아무리 노력해도 짧아지지 않을 때는 유의어를 써보세요. (https://www.thesaurus.com)

 

p.64

- 단어 풀 만들기. 우리 팀에서는 '변경'이란 의미를 표현할 때 'edit'나 'modify'가 아닌 'change'를 쓴다고 명시해두는 거죠.

 

p.64~67

커밋 메세지 본문 쓰기

  - 커밋한 이유를 알려주세요

    * 커밋한 이유, 커밋하게 된 계기를 적어야 합니다.

  - 외부 자원을 명시해주세요

    * 새롭게 이용하게 된 외부 라이브러리나 패키지가 있다면 기재해주세요.

  - 선택한 이유를 알려주세요

    * 커밋에 반영된 선택을 한 이유를 본문에 남겨주세요. 

    * 코드 리뷰어도 왜 이렇게 하지 않았냐고 질문하지 않을 수 있습니다.나중에 관련 작업을 할 때도 유용한 정보가 됩니다. 

  - 관련 자료를 첨부해주세요

    * 커밋 메시지에도 정보 자체를 상세히 남기길 권합니다. 자료에 있는 글을 '복붙'을 하더라도요.