좋은 CL 설명을 작성하는 방법
CL 설명이란 어떤 변화가 일어나고 왜 그것이 만들어졌는지에 대한 기록입니다. 그것은 버전 관리 역사에 영구적인 부분이 될 것이고, 수년간 당신의 리뷰어 외에 수백 명의 사람들에게 읽힐 것입니다. 향후에 개발자는 당신의 CL 설명을 기반으로 CL을 찾을 것입니다. 모든 중요한 정보가 설명문이 아닌 코드에 있다면, 그들은 당신의 CL을 찾기가 훨씬 더 어려울 것입니다.
첫 줄
- 수행중인 작업에 대한 간략한 요약
- 명령문처럼 쓰여진 완전한 문장
- 바로 뒤에 줄 바꿈
CL 설명의 첫 번째 줄은 어떤 작업을 했는지에 대한 간략한 요약이며, 그 뒤에 공백줄이 있어야 합니다. 향후에 코드 이력을 검색하는 사람이 보게되므로 첫 번째 줄은 당신의 CL 또는 전체 설명을 읽을 필요가 없을만큼 충분한 정보를 주어야 합니다. 그래야 당신의 CL이 실제로 무엇을 하는지 이해할 수 있습니다.
관례로, CL의 첫 번째 줄은 완전한 문장으로 명령문처럼 작성합니다. 예를 들면, “FizzBuzz RPC 삭제와 새 시스템으로 교체” 대신에 “FizzBuzz RPC를 삭제하고 새 시스템으로 교체한다” 라고 작성합니다. 하지만 설명문의 나머지 부분은 명령문 형태로 작성하지 않아도 됩니다.
정보를 주는 본문
나머지 설명은 유용해야 합니다. 문제에 대한 설명과 이것이 왜 가장 좋은 방법인지에 대한 것일 수 있습니다. 만약 방법에 문제가 있다면, 설명에 포함해야 합니다. 관련 이슈 번호나 벤치마크 결과 그리고 설계 문서 링크와 같은 배경 정보를 포함합니다. 작은 CL 조차도 세부사항에 약간의 주의를 기울일만 합니다.
좋지 않은 CL 설명
“버그 수정”은 적절하지 않은 CL 설명입니다. 무슨 버그인가요? 문제를 해결하기 위해 무엇을 했나요? 다른 유사한 나쁜 사례는 다음과 같습니다.
- “빌드 수정”
- “패치 추가”
- “A에서 B로 코드 이동”
- “1단계”
- “편의 함수 추가”
- “이상한 URL 제거”
일부는 실제 CL 설명입니다. 저자들은 그들이 유용한 정보를 제공하고 있다고 생각할지 모르지만 CL 설명의 목적을 제공하고 있지 않습니다.
좋은 CL 설명
다음은 좋은 설명의 몇 가지 예시입니다.
기능 변경
rpc: RPC 서버 메시지 빈칸 목록에서 크기 제한을 제거합니다.
FizzBuzz와 같은 서버에는 매우 큰 메시지들이 있고 재사용 이점이 있습니다. 빈칸 목록을 더 크게 만들고 시간이 지남에 따라 천천히 빈칸 목록을 해제하는 고루틴(goroutine)을 추가합니다. 따라서 유휴 서버는 모든 빈칸 목록을 해제합니다.
처음 몇 가지 단어들은 CL이 실제로 무엇을 하는지 설명합니다. 나머지 설명서는 해결되는 문제, 왜 이것이 좋은 해결책인지, 그리고 조금 더 많은 구체적인 구현에 대한 정보를 설명하고 있습니다.
리팩토링
TimeKeeper를 사용하여 TimeStr과 Now 메서드를 사용하도록 태스크를 구성한다.
태스크에 Now 메서드를 추가하여, borglet() 접근자 메서드를 제거할 수 있습니다. (OOMCandidate에서 borglet의 Now 메서드 호출하는데만 사용) 이것은 TimeKeeper에 위임하는 Borglet 메서드를 대체합니다. 결국, Now 메서드를 가져오는데 의존하는 것들은 TimeKeeper를 직접 사용하도록 변경되어야 하지만 리팩토링하기 위한 것입니다. Borglet Hierarchy를 리팩토링하는 장기 목표를 계속합니다.
첫 번째 줄에는 CL이 하는 것과 과거와 어떻게 다른지 설명합니다. 나머지 설명에서는 특정 구현, CL의 문맥, 현재 해결방안이 이상적이지 않으며 향후 방향헤 대해서 설명합니다. 또한 이 변경을 진행하는 이유에 대해서도 설명합니다.
문맥(Context)이 필요한 작은 CL
status.py에 대한 python3 빌드 규칙을 작성한다.
이를 통해 python3을 사용하는 사람들도 원래의 빌드 규칙에 의존할 수 있습니다. 그리고 이는 python2 대신 python3을 사용하도록 권장하고 현재 작업중인 일부 자동화 빌드 파일 리팩토링 도구를 단순화시킵니다.
첫 번째 문장은 실제로 무엇을 하고 있는지 설명합니다. 나머지 설명은 수행되는 이유를 설명하고 리뷰어에게 많은 맥락(Context)을 제공합니다.
CL을 반영하기 전에 설명문 검토하기
CL은 코드 리뷰를 하면서 많이 변경될 수 있습니다. CL이 반영(머지)되기 전에 관련 설명문이 CL이 수행하는 일을 반영하는지 확인하는 것이 좋습니다.
