코드 리뷰 이야기를 할 때 사람들은 대개 리뷰어에게 초점을 맞춥니다. 하지만 코드를 작성하는 개발자는 코드를 읽는 사람만큼이나 리뷰에서 중요한 역할을 합니다. 코드를 리뷰에 내놓기 위해 어떻게 준비해야 하는지에 대한 안내는 거의 찾아볼 수 없고, 그래서 작성자들은 순전히 몰라서 이 과정을 망치곤 합니다.

이 글에서는 코드 리뷰에 작성자로 참여할 때의 모범 사례를 소개합니다. 사실 이 글을 다 읽고 나면 여러분은 코드 리뷰를 요청하는 일을 너무나 잘하게 되어 리뷰어가 말 그대로 여러분에게 반하게 될 것입니다.

하지만 리뷰어가 저에게 반하는 건 원치 않는데요

어차피 반하게 될 겁니다. 받아들이세요. 죽음을 앞두고 너무 많은 사람이 자신을 사랑했다고 불평한 사람은 아무도 없습니다.

왜 코드 리뷰를 개선해야 할까요?

코드 리뷰 기술을 개선하면 리뷰어와 팀, 그리고 무엇보다 여러분 자신에게 도움이 됩니다.

• 더 빠르게 성장합니다: 체인지리스트를 제대로 준비하면 리뷰어의 관심이 지루한 스타일 위반이 아니라 여러분의 성장을 돕는 영역에 집중됩니다. 건설적인 비판을 고맙게 받아들인다는 태도를 보이면 리뷰어는 더 좋은 피드백을 제공합니다.

• 동료를 더 뛰어나게 만듭니다: 여러분의 코드 리뷰 방식은 동료들에게 모범이 됩니다. 효과적인 작성자 습관은 팀원들에게 전염되고, 이는 그들이 여러분에게 코드를 보낼 때 여러분의 일을 더 수월하게 만듭니다.

• 팀 내 갈등을 줄입니다: 코드 리뷰는 마찰이 생기기 쉬운 지점입니다. 의도적이고 성실하게 접근하면 논쟁을 최소화할 수 있습니다.

황금률: 리뷰어의 시간을 소중히 여기세요

이 조언은 당연하게 들리지만, 저는 작성자들이 리뷰어를 마치 개인 QA 담당자처럼 대하는 경우를 자주 봅니다. 이런 작성자들은 자신의 실수를 직접 잡거나 리뷰하기 쉬운 체인지리스트를 만들려는 노력을 전혀 하지 않습니다.

동료는 매일 한정된 집중력을 가지고 출근합니다. 그중 일부를 여러분에게 할애한다면 그 시간만큼 자신의 업무에 쓸 수 없게 됩니다. 그들의 시간이 최대한 가치 있게 쓰이도록 하는 것이 도리입니다.

리뷰는 두 참여자가 서로를 신뢰할 때 비약적으로 좋아집니다. 리뷰어는 여러분이 피드백을 진지하게 받아들일 것이라 믿을 때 더 많은 노력을 기울입니다. 리뷰어를 넘어서야 할 장애물로 바라보면 그들이 제공할 수 있는 가치가 제한됩니다.

실전 기법

1. 먼저 자신의 코드를 직접 리뷰하세요
2. 명확한 체인지리스트 설명을 작성하세요
3. 쉬운 일은 자동화하세요
4. 질문에 대해서는 코드 자체로 답하세요
5. 변경 범위를 좁게 유지하세요
6. 기능적 변경과 비기능적 변경을 분리하세요
7. 큰 체인지리스트는 나누세요
8. 비판에 우아하게 대응하세요
9. 리뷰어가 틀렸을 때도 인내심을 가지세요
10. 대응 내용을 명시적으로 전달하세요
11. 부족한 정보를 센스 있게 요청하세요
12. 애매하면 리뷰어에게 양보하세요
13. 리뷰 라운드 사이의 지연을 최소화하세요

1. 먼저 자신의 코드를 직접 리뷰하세요

동료에게 코드를 보내기 전에 스스로 읽어보세요. 단순히 실수를 찾는 데 그치지 말고, 처음 보는 코드를 읽는다고 상상해 보세요. 무엇이 헷갈릴까요?

저는 코드를 작성한 뒤 리뷰하기 전까지 잠시 쉬는 것이 도움이 된다고 생각합니다. 많은 사람이 하루가 끝날 때 변경 사항을 쏘아 보내곤 하는데, 그때가 부주의한 실수를 놓치기 가장 쉬운 순간입니다. 아침까지 기다렸다가 새로운 눈으로 체인지리스트를 살펴본 뒤 동료에게 넘기세요.

가능한 한 리뷰어의 환경을 그대로 따라 해 보세요. 리뷰어가 보게 될 것과 동일한 diff 뷰를 사용하세요. 일반적인 소스 에디터보다 diff 뷰에서 어리석은 실수를 찾기가 더 쉽습니다.

자신에게 완벽을 기대하지 마세요. 결국 디버깅 코드를 삭제하지 않고 보내거나 제외하려던 파일을 실수로 포함하는 등 실수를 하게 마련입니다. 이런 실수가 세상의 끝은 아니지만 추적해 볼 가치는 있습니다. 자신의 실수 패턴에 주의를 기울이고 이를 방지할 시스템을 만들 방법을 고민해 보세요. 너무 자주 발생한다면 리뷰어의 시간을 소중히 여기지 않는다는 신호로 비칠 수 있습니다.

2. 명확한 체인지리스트 설명을 작성하세요

이전 직장에서 저는 개발자 멘토링 프로그램의 일환으로 시니어 엔지니어와 정기적으로 만났습니다. 첫 미팅 전에 그는 제가 작성한 설계 문서를 가져오라고 했습니다. 문서를 건네며 저는 프로젝트가 무엇인지, 팀 목표와 어떻게 부합하는지 설명했습니다. 멘토는 인상을 찌푸렸습니다. “방금 말한 내용은 설계 문서 첫 페이지에 다 있어야 하는 거야”라고 그는 단호하게 말했습니다.

그는 옳았습니다. 저는 팀 동료들이 문서를 어떻게 읽을지를 상상하며 설계 문서를 썼지만, 다른 독자를 고려하지 못했습니다. 바로 옆 팀 동료 너머로 파트너 팀, 멘토, 그리고 승진 심사 위원회까지 더 넓은 독자가 있었습니다. 그들 모두가 문서를 이해할 수 있어야 했습니다. 그 대화 이후로 저는 항상 제 작업의 맥락을 어떻게 설명할지 고민합니다.

체인지리스트 설명은 독자가 필요로 하는 배경 지식을 요약해야 합니다. 설명을 쓸 때는 특정 코드 리뷰어를 염두에 둘 수 있지만, 그 사람이 여러분이 상상하는 맥락을 모두 가지고 있지는 않을 수 있습니다. 게다가 다른 팀원들도 이 체인지리스트를 읽어야 할 수 있고, 미래의 독자들도 변경 이력을 돌아볼 때 여러분의 의도를 이해할 수 있어야 합니다.

좋은 체인지리스트 설명은 이 변경이 높은 수준에서 무엇을 달성하는지, 그리고 왜 이런 변경을 하는지를 설명합니다.

훌륭한 체인지리스트 설명에 대해 더 깊이 알고 싶다면 제 글 “유용한 커밋 메시지 작성법(How to Write Useful Commit Messages)”을 참고하세요.

3. 쉬운 일은 자동화하세요

중괄호가 잘못된 줄에 있는지, 혹은 여러분의 변경이 자동화된 테스트 스위트를 깨뜨렸는지를 리뷰어에게 의존해 알려달라고 한다면 여러분은 그들의 시간을 낭비하는 것입니다.

자동화된 테스트는 팀의 표준 워크플로에 포함되어야 합니다. 리뷰는 모든 자동 검사가 지속적 통합 환경에서 통과한 뒤에 시작됩니다.

만약 팀이 안타깝게도 잘못된 방향으로 가고 있어 지속적 통합에 투자하기를 거부한다면, 이런 검사를 직접 자동화하세요. git pre-commit hook과 린터, 포매터를 개발 환경에 추가해 매 커밋마다 코드가 적절한 컨벤션을 따르고 의도한 동작을 유지하도록 하세요.

4. 질문에 대해서는 코드 자체로 답하세요

이 그림의 무엇이 잘못되었을까요?

작성자는 제가 함수를 이해하도록 도왔지만, 다음에 이 코드를 읽는 사람은 어떨까요? 변경 이력을 파헤쳐 지금까지의 모든 코드 리뷰 논의를 읽어야 할까요? 더 나쁜 경우는 작성자가 제 책상까지 와서 직접 설명해 주는 것으로, 이는 제 집중을 방해할 뿐 아니라 다른 누구도 그 정보에 접근할 수 없게 만듭니다.

리뷰어가 코드 동작에 대해 혼란을 표현할 때 해결책은 그 한 사람에게 설명하는 것이 아닙니다. 모든 사람에게 설명해야 합니다.

누군가의 질문에 답하는 가장 좋은 방법은 코드를 리팩터링하여 혼란 자체를 없애는 것입니다. 더 명확하게 만들도록 이름을 바꾸거나 로직을 재구성할 수 있을까요? 코드 주석도 괜찮은 해결책이지만, 자연스럽게 스스로를 설명하는 코드보다는 분명히 못한 방법입니다.

5. 변경 범위를 좁게 유지하세요

스코프 크리프는 코드 리뷰에서 흔한 안티패턴입니다. 개발자가 논리 버그를 고치기 시작하다가 그 과정에서 UI의 사소한 결함을 발견합니다. “어차피 여기 왔으니 이것도 고치지 뭐”라고 생각합니다. 하지만 이제 상황이 뒤섞였습니다. 리뷰어는 어떤 변경이 목표 A를 위한 것이고 어떤 변경이 목표 B를 위한 것인지 파악해야 합니다.

최고의 체인지리스트는 그저 한 가지 일만 합니다(Do One Thing). 변경이 더 작고 단순할수록 리뷰어가 모든 맥락을 머릿속에 담아두기가 더 쉽습니다. 관련 없는 변경을 분리하면 리뷰를 팀원들에게 병렬로 분산시켜 변경 사항의 처리 시간을 단축할 수도 있습니다.

6. 기능적 변경과 비기능적 변경을 분리하세요

범위를 최소화하라는 원칙의 당연한 귀결은 기능적 변경과 비기능적 변경을 분리하는 것입니다.

코드 리뷰에 익숙하지 않은 개발자들은 종종 이 규칙을 어깁니다. 두 줄을 변경했는데 코드 에디터가 파일 전체를 자동으로 다시 포맷해 버리는 경우가 있습니다. 개발자는 자신이 무슨 짓을 했는지 알아채지 못하거나 새로운 포맷이 더 낫다고 판단합니다. 그래서 두 줄짜리 기능 변경이 수백 줄의 비기능적 공백 변경 속에 파묻힌 채 리뷰 요청을 보내게 됩니다.

뒤섞인 체인지리스트는 리뷰어에게 엄청난 무례입니다. 공백만 바꾼 변경은 리뷰하기 쉽습니다. 두 줄 변경도 리뷰하기 쉽습니다. 하지만 공백 변경의 바다 속에 파묻힌 두 줄 기능 변경은 지루하고 진을 빠지게 만듭니다.

개발자들은 리팩터링을 하면서도 변경을 부적절하게 섞는 경향이 있습니다. 저는 팀원들이 코드를 리팩터링하는 것을 좋아하지만, 코드 동작을 바꾸면서 동시에 리팩터링하는 것은 싫어합니다.

코드 한 조각에 리팩터링과 동작 변경이 모두 필요하다면, 두세 개의 체인지리스트로 나누어 진행해야 합니다:

1. 기존 동작을 검증하는 테스트를 추가합니다(아직 없다면).
2. 테스트 코드는 그대로 둔 채 프로덕션 코드를 리팩터링합니다.
3. 프로덕션 코드의 동작을 변경하고 그에 맞춰 테스트를 업데이트합니다.

2단계에서 자동화된 테스트를 그대로 둠으로써 리팩터링이 동작을 보존한다는 것을 리뷰어에게 증명할 수 있습니다. 3단계에 도달하면 미리 분리를 해두었기 때문에 리뷰어가 동작 변경과 리팩터링 변경을 뒤섞어 풀어낼 필요가 없습니다.

7. 큰 체인지리스트는 나누세요

지나치게 큰 체인지리스트는 스코프 크리프의 못생긴 사촌 격입니다. 개발자가 기능 X를 도입하기 위해 기존 라이브러리 A와 B의 의미를 수정해야 한다고 가정해 보세요. 변경 집합이 작다면 괜찮지만, 이런 광범위한 수정이 너무 많아지면 체인지리스트가 방대해집니다.

체인지리스트의 복잡도는 건드리는 코드 줄 수에 따라 기하급수적으로 증가합니다. 프로덕션 코드가 400줄을 넘어가면 리뷰를 요청하기 전에 나눌 기회를 찾아봅니다.

모든 것을 한 번에 바꾸는 대신, 먼저 의존성을 변경한 뒤 다음 체인지리스트에서 새 기능을 추가할 수 없을까요? 코드베이스를 정상적인 상태로 유지하면서 기능의 절반은 지금 추가하고 나머지는 다음 체인지리스트에서 추가할 수는 없을까요?

작동하면서 이해 가능한 변경이 되는 하위 집합을 찾으려고 코드를 나누는 일은 지루하지만, 더 나은 피드백을 얻고 리뷰어에게 가해지는 부담을 줄일 수 있습니다.

8. 비판에 우아하게 대응하세요

코드 리뷰를 망치는 가장 빠른 방법은 피드백을 개인적인 공격으로 받아들이는 것입니다. 많은 개발자가 자신의 작업에 자부심을 가지고 이를 자신의 연장으로 여기기 때문에 이는 쉽지 않습니다. 리뷰어가 여러분의 피드백을 무례하게 개인 공격처럼 표현하면 더욱 어렵습니다.

작성자로서 피드백에 대한 반응을 궁극적으로 통제하는 것은 여러분 자신입니다. 리뷰어의 지적을 여러분이라는 인간의 개인적 가치에 대한 논의가 아니라 코드에 대한 객관적인 논의로 받아들이세요. 방어적으로 대응하면 상황만 더 악화될 뿐입니다.

저는 모든 지적을 도움이 되는 교훈으로 해석하려고 노력합니다. 리뷰어가 제 코드에서 창피한 버그를 잡아낼 때 제 첫 충동은 변명하는 것입니다. 대신 스스로를 다잡고 리뷰어의 꼼꼼함에 대해 칭찬합니다.

놀랍게도 리뷰어가 여러분 코드에서 미묘한 결함을 발견하는 것은 좋은 신호입니다. 체인지리스트를 잘 포장하고 있다는 뜻이기 때문입니다. 잘못된 포맷이나 헷갈리는 이름 같은 명백한 문제들이 없으면 리뷰어는 로직과 설계에 깊이 집중할 수 있어 더 가치 있는 피드백을 남길 수 있습니다.

9. 리뷰어가 틀렸을 때도 인내심을 가지세요

때때로 리뷰어는 완전히 틀리기도 합니다. 여러분이 실수로 버그 있는 코드를 작성할 수 있는 것처럼 리뷰어도 올바른 코드를 오해할 수 있습니다.

많은 개발자가 리뷰어의 실수에 방어적으로 반응합니다. 사실도 아닌 비판으로 자신의 코드가 모욕당했다는 모욕으로 받아들입니다.

리뷰어가 틀렸을 때조차 그것은 여전히 위험 신호입니다. 그 사람이 잘못 읽었다면 다른 사람도 같은 실수를 하지 않을까요? 독자가 특정 버그가 존재하지 않는다는 것을 스스로 확신하기 위해 비정상적인 수준의 세심함을 발휘해야 할까요?

코드를 리팩터링하거나 주석을 추가해 코드가 더 명백하게 올바르게 보이도록 할 방법을 찾아보세요. 혼란이 생소한 언어 기능에서 비롯된 것이라면, 전문가가 아닌 사람도 이해할 수 있는 메커니즘을 사용해 코드를 다시 작성하세요.

10. 대응 내용을 명시적으로 전달하세요

저는 누군가에게 지적 사항을 남겼는데 상대방이 피드백 중 일부만 반영해 코드를 업데이트하고 아무런 답글도 남기지 않는 상황을 자주 마주합니다. 이제 우리는 모호한 상태에 놓입니다. 상대방이 나머지 지적을 놓친 걸까요, 아니면 아직 작업 중일까요? 제가 새로운 라운드의 리뷰를 시작하면 아직 완성되지 않은 체인지리스트에 시간을 낭비할 수도 있습니다. 기다리면 둘 다 상대방이 다음 차례라고 기대하며 교착 상태에 빠질 수도 있습니다.

팀 내에서 언제나 누가 ‘바통을 쥐고’ 있는지 명확히 하는 규칙을 정하세요. 작성자가 수정을 작업 중이거나 리뷰어가 피드백을 작성 중이어야 합니다. 아무도 누가 무엇을 해야 하는지 몰라 프로세스가 멈추는 상황은 절대 없어야 합니다. 이는 체인지리스트 수준의 댓글로 언제 제어를 넘기는지 표시하면 쉽게 달성할 수 있습니다.

조치가 필요한 모든 지적에 대해 명시적으로 대응하여 처리했음을 확인해 주세요. 일부 코드 리뷰 도구는 댓글을 해결됨으로 표시할 수 있게 합니다. 그렇지 않다면 각 지적에 대해 “완료했습니다”와 같은 간단한 관례를 따르세요. 지적에 동의하지 않는다면 왜 조치를 취하지 않았는지 정중하게 설명하세요.

리뷰어가 들인 노력에 맞춰 대응 방식을 조정하세요. 리뷰어가 여러분에게 새로운 것을 알려주기 위해 상세한 지적을 남겼다면 단순히 완료 표시만 하지 마세요. 그들의 노력에 감사함을 담아 사려 깊게 답하세요.

11. 부족한 정보를 센스 있게 요청하세요

때로는 코드 리뷰 코멘트가 너무 많은 해석의 여지를 남깁니다. “이 함수는 헷갈린다”는 코멘트를 받으면 ‘헷갈린다’는 게 정확히 무엇을 의미하는지 궁금해질 것입니다. 함수가 너무 긴 걸까요? 이름이 불명확한 걸까요? 문서가 더 필요한 걸까요?

오랫동안 저는 방어적으로 들리지 않으면서 모호한 지적을 명확히 하려고 애썼습니다. 본능적으로 “뭐가 헷갈린다는 거죠?”라고 묻고 싶었지만, 그렇게 물으면 투덜대는 것처럼 들립니다.

한번은 제가 무심코 모호한 지적을 보냈는데, 동료가 정말 영리하게 답한 적이 있습니다:

어떤 변경이 도움이 될까요?

저는 이 응답이 정말 마음에 듭니다. 방어적이지 않고 비판을 열린 마음으로 받아들인다는 신호를 보내기 때문입니다. 리뷰어로부터 불명확한 피드백을 받을 때마다 저는 항상 “어떤 것이 도움이 될까요?”라는 식으로 답합니다.

또 다른 유용한 방법은 리뷰어의 의도를 추측하고 그 가정을 바탕으로 선제적으로 코드를 수정하는 것입니다. “이건 헷갈린다”는 지적에 대해 코드를 다시 한번 살펴보세요. 대개 명확성을 높이기 위해 할 수 있는 무언가가 있습니다. 수정 자체가 리뷰어에게 여러분이 변화를 기꺼이 수용한다는 것을 보여주며, 설령 그것이 그들이 염두에 둔 변경이 아니더라도 마찬가지입니다.

12. 애매하면 리뷰어에게 양보하세요

테니스에서는 상대의 서브가 아웃인지 확신이 서지 않을 때 상대에게 유리하게 판정합니다. 코드 리뷰에서도 비슷한 기대가 있어야 합니다.

코드에 대한 일부 결정은 취향의 문제입니다. 리뷰어가 8줄짜리 함수가 5줄짜리 함수 두 개로 나뉘면 더 낫겠다고 생각한다면, 누구도 객관적으로 “맞다”고 할 수 없습니다. 어느 버전이 더 나은지는 의견의 문제입니다.

리뷰어가 제안을 했을 때 여러분 각자가 자신의 입장을 뒷받침할 비슷한 수준의 근거를 가지고 있다면 리뷰어에게 양보하세요. 두 사람 중에서는 코드를 처음 보는 리뷰어가 이 코드를 새로 읽는 것이 어떤 느낌인지에 대해 더 나은 관점을 가지고 있습니다.

13. 리뷰 라운드 사이의 지연을 최소화하세요

몇 달 전, 한 사용자가 제가 유지 관리하는 오픈소스 프로젝트에 작은 변경을 기여했습니다. 저는 몇 시간 안에 피드백을 주었지만 그들은 곧바로 사라졌습니다. 며칠 뒤 다시 확인했지만 여전히 답이 없었습니다.

6주 뒤, 그 신비한 개발자가 수정 사항을 제출하며 다시 나타났습니다. 그들의 노력에는 감사했지만 라운드 사이의 지연 때문에 제 작업량은 두 배가 되었습니다. 코드를 다시 읽어야 했을 뿐 아니라 논의 내용을 기억하기 위해 제 피드백까지 다시 읽어야 했습니다. 하루 이틀 안에 후속 조치를 했다면 그런 추가 작업을 할 필요가 없었을 것입니다.

6주간의 중단은 극단적인 예지만, 저는 팀원들 사이에서도 길고 불필요한 지연을 자주 봅니다. 누군가 리뷰를 위해 체인지리스트를 보내고 피드백을 받은 뒤 다른 업무 때문에 일주일 동안 뒷전으로 미뤄두는 경우입니다.

맥락을 복원하는 데 드는 시간 손실 외에도, 미완성 체인지리스트는 복잡성을 증가시킵니다. 이미 머지된 것과 진행 중인 것을 모두가 추적하기 더 어렵게 만듭니다. 부분적으로 완료된 체인지리스트가 많아질수록 머지 충돌도 늘어나고, 그걸 좋아하는 사람은 아무도 없습니다.

일단 코드를 보내면 리뷰를 완료까지 끌고 가는 것이 최우선 과제가 되어야 합니다. 여러분 쪽에서의 지연은 리뷰어의 시간을 낭비하고 팀 전체의 복잡성을 증가시킵니다.

결론

다음 체인지리스트를 리뷰에 내놓을 준비를 하면서 여러분이 통제할 수 있는 요소들을 고려하고 이를 활용해 리뷰를 생산적으로 이끌어 보세요. 리뷰에 참여하면서 진행을 가로막거나 노력을 낭비하는 패턴이 있는지 살펴보세요.

황금률을 기억하세요: 리뷰어의 시간을 소중히 여기세요. 리뷰어가 여러분 코드의 흥미로운 부분에 집중할 수 있게 하면 수준 높은 피드백을 만들어냅니다. 코드를 풀어내거나 단순한 실수를 단속하도록 요구하면 둘 다 손해를 봅니다.

마지막으로, 사려 깊게 소통하세요. 단순한 오해나 경솔한 한마디로 리뷰가 쉽게 탈선할 수 있습니다. 누군가의 작업을 비판할 때는 감정이 격해지기 쉬우므로 리뷰어가 공격받거나 무례함을 느꼈다고 느낄 수 있는 함정을 의식하세요.

축하합니다! 여기까지 도달했다면 이제 여러분은 훌륭한 피리뷰이가 되었습니다. 리뷰어는 아마 여러분에게 반했을 것이니 잘 대해 주세요.

더 읽어보기

• 사람답게 코드 리뷰하는 법: 작성자 측면에서의 효과적인 방법을 배웠으니 이제 리뷰어로서 코드 리뷰를 개선하는 방법을 배워 보세요.

일러스트: Loraine Yow. 편집: Samantha Mason.