좋은 CL 설명문 쓰는 법
CL 설명문이란 코드에 어떤 변화가 있고 왜 그런 변화가 필요한지를 설명하는 기록물이다. 앞으로 수 백 명의 개발자들이 당신이 작성했던 CL을 찾고 과거 기록을 보고 코드를 더 잘 이해할 수 있게 된다. 중요한 정보가 코드에만 있고 설명문이 없다면 과거의 CL을 찾아보기가 너무 어려울 것이다.
첫 줄
명령문 형태로 어떤 작업이 이뤄졌는지 설명하고 줄바꿈을 한번 한다. 첫번째 줄은 명확하고 간략하게 작성하여 코드 이력을 찾아보는 개발자가 한 눈에 알아볼 수 있게 한다.
본문에는 유용한 정보를 담는다
첫 줄 이후 본문에는 CL이 해결한 문제를 적고 왜 이게 최선의 해결책인지 설명한다. 해결책에 기술적인 결점이 있다면 이 또한 포함시킨다. 이슈 트래킹 넘버나 참고 문서를 덧붙여도 좋다. 작고 사소한 CL에도 배경 설명을 꼭 한다.
안 좋은 CL 설명문
“버그 수정”은 CL 설명문으로는 빈약하다.
- “패치”
- “B에 있던코드를 A로 이동”
- “함수 추가”
- “이상한 URL 제거”
등도 마찬가지다. 앞서 언급한 것들은 실제 존재하는 CL 설명문들인데 설명문을 쓰는 목적에 부합하지 않는다.
좋은 CL 설명문
좋은 설명문은 CL이 무얼 하고 있는지 첫 줄에 설명한다. 본문에는 어떤 문제를 해결하는지, 왜 이렇게 해결했는지, 그리고 코드에 대한 설명도 있고 해당 CL에 대한 배경 설명과 추후 발전 방향이 포함될 수도 있다.
CL을 머지하기 전 설명문 검토하기
코드 리뷰를 거치면서 꽤 많은 것이 바뀌었을 수도 있다. 최종적으로 코드를 머지하기 전 설명문에 변경 사항이 반영되어 있는지 꼭 확인한다.
다음: 작게 쪼개기