이 문서는 CL Tips(
docs/cl_tips.md) 문서의 한국어 전체 번역입니다.
이 페이지는 CL 작성자와 리뷰어 모두가 더 생산적이고, 효율적이며, 서로에게 유익한 코드 리뷰를 할 수 있도록 돕기 위한 것이다. 이 팁들 중 어느 것도 공식 정책을 나타내지는 않지만, 이 지침을 따르면 변경사항을 더 빠르게 리뷰받고 랜딩하는 데 도움이 될 것이다.
Respectful Changes와 Respectful Code Reviews도 함께 읽어 보라.
변경사항을 500 LoC 미만으로 유지하라
큰 변경사항은 작은 변경사항보다 리뷰하는 데 더 오래 걸린다. 리뷰어는 일반적으로 리뷰의 각 라운드가 끝난 뒤 CL의 내용을 다시 익혀야 하므로, CL이 클수록 그 과정에 더 많은 시간이 걸린다. 큰 CL은 CL을 한 줄씩 살펴보는 리뷰어를 지치게 만들 수도 있다. 테스트를 포함해 변경사항을 코드 500줄 미만으로 유지하려고 하라. 다만 여기에는 균형이 있다. 프로덕션 코드 200줄(LoC)에 테스트 600줄은 괜찮을 수 있으며, 특히 테스트 코드가 규칙적인 패턴을 따른다면 더욱 그렇다. 반대로 프로덕션 코드 400줄에 테스트 코드 200줄은 충분한 커버리지를 제공하지 못할 수 있다.
CL이 그보다 크다면, 더 작고 리뷰 가능한 단위로 나누는 것을 진지하게 고려하라. CL을 나눌 때는 연관성이 명확하도록 각 CL에 동일한 추적 버그를 태그해야 한다. 또한 리뷰어가 랜딩되기 전 진행 과정을 볼 수 있도록 의존 CL의 relation chain을 사용할 수도 있다.
CL에 대한 맥락을 공유하라
리뷰를 위한 맥락을 제공하는 것은 변경의 동기를 이해하는 데 중요하다. 공유해야 할 맥락의 양은 변경의 규모에 따라 달라진다. 하나의 독립적인 패치에는 충실한 CL 설명만으로도 충분할 수 있다. 하지만 때로는 링크된 버그에 맥락을 제공하는 것이 더 나을 수 있는데, 예를 들어 제안된 수정으로 이어진 조사를 문서화하는 경우가 그렇다. 변경사항이 크다면, design doc을 통해 리뷰어에게 일련의 소규모에서 중간 규모 CL들에 대한 맥락을 제공하는 것이 도움이 된다. 해결해야 할 문제, 제안된 해결책에 대한 전반적인 설명, 그리고 고려했던 대안들을 강조하라.
CL 설명은 항상 무엇을 변경하는지와 왜 변경하는지를 문서화해야 한다. CL 설명은 저장소 히스토리에 저장되므로, 시간이 지나도 견딜 수 있도록 작성해야 한다. 스스로에게 물어보라. “지금부터 5년 뒤 다른 엔지니어가 설명만을 바탕으로 이 CL이 왜 랜딩되었는지 이해해야 한다면, 이해할 수 있을까?”
복잡한 CL에서는 리뷰어를 안내하라
CL 설명은 기록으로 남지만, CL에 댓글을 남길 수도 있다. CL에 하나의 주요 변경사항과 그 변경으로 인한 많은 후속 영향이 포함되어 있다면, 리뷰 과정을 어디서 시작해야 하는지 짚어 줄 수 있다. 소스 코드에 주석을 달 정도는 아니지만 설계 결정이나 트레이드오프를 했다면, 리뷰어에게 알리기 위해 CL에 선제적으로 댓글을 남길 수도 있다.
동작 변경과 리팩터링을 분리하라
CL은 한 가지 유형의 변경만 수행해야 한다. 무언가를 리팩터링하면서 동시에 그 동작을 변경해야 한다면, 두 개의 별도 CL로 나누어 진행하는 것이 가장 좋다. 일반적으로 리팩터링은 동작을 변경해서는 안 된다. 이는 리뷰어에게 이득이 되는데, 리뷰어는 동작을 변경하지 않는 코드 이동만의 변경으로서 리팩터링을 더 빠르게 평가할 수 있다. 또한 작성자에게도 이득이 되는데, 동작 변경으로 인한 회귀 때문에 불필요한 revert와 re-land를 겪을 가능성을 줄일 수 있기 때문이다.
복잡성은 캡슐화하되, 과도하게 추상화하지는 말라
변경사항을 작게 유지하는 한 가지 방법은 독립적으로 테스트하고 리뷰할 수 있는 조합 가능한 단위(함수, 클래스, 인터페이스)를 구축해 나가는 것이다. 이는 전체 변경 규모를 관리하는 데 도움이 되며, 리뷰어가 따라갈 수 있는 자연스러운 진행 흐름을 만든다. 그러나 알 수 없는 미래를 위해 추상화를 과도하게 설계하지는 말라. 필요하지 않은데도 확장 가능성을 허용하거나, 구체적인 것으로 충분한 곳에 추상화를 만들거나, 더 단순한 것이 똑같이 잘 작동할 때 디자인 패턴을 선택하는 것은 코드베이스에 불필요한 복잡성을 더한다. 코드베이스는 본질적으로 변경 가능하며, 추가 추상화는 필요해지는 경우와 시점에 추가할 수 있다.
적절한 리뷰어 선택하기
가장 적합한 연락 대상을 식별하는 방법에 대한 자세한 내용은 코드 조각이 어떻게 동작하는지 아는 사람 찾기를 보라.
시간대 지연을 줄이도록 최적화하라
Chromium 프로젝트에는 전 세계의 기여자들이 있으며, 리뷰어와 같은 시간대에 있지 않을 가능성이 매우 높다. 코드 리뷰 정책에 따라 리뷰어가 응답할 것이라고 기대해야 하지만, 상당한 시간대 차이가 있을 수 있다는 점을 염두에 두라. 시간대 간 지연 최소화에 대한 조언도 참고하라.
여러 OWNER에게 요청하기 전에, 한 명의 주 리뷰어에게 전체 리뷰를 받아라
CL에 3명 이상의 OWNER 승인이 필요하다면, OWNER들이 누구나 발견할 수 있는 문제를 처리할 필요가 없도록 소수의 주 리뷰어(가장 흔하게는 1명)에게 전체 CL을 리뷰받아라. 이는 OWNER들이 다른 시간대에 있을 때 특히 유용하다.
더 구체적인 owner에게 의존하라
가능한 경우, 변경사항의 가장 중요한 측면과 인접한 가장 깊은 OWNERS 파일에서 리뷰어를 선택하라. 그들의 리뷰가 완료되면, API 변경 전파에 대한 승인을 받기 위해 상위/덜 구체적인 디렉터리의 OWNERS를 추가하라. 상위 디렉터리 리뷰어는 일반적으로 더 구체적인 리뷰어의 LGTM에 따르고 단순히 CL에 승인 도장을 찍을 수 있다.
하나의 변경사항을 리뷰하도록 동일한 OWNERS 파일에서 여러 리뷰어를 추가하는 것은 피하라. 이렇게 하면 각 리뷰어의 책임이 무엇인지 불명확해진다. 필요한 것은 OWNER의 LGTM 하나뿐이므로, 한 명만 선택하면 된다. 파일 리비전 히스토리를 사용해 어떤 리뷰어가 해당 영역에서 더 최근에 활동했는지 확인할 수 있다.