코드 리뷰 연습: 동료 리뷰를 활용하여 분석력과 기술적 판단력을 기르는 방법

한 개발자가 결제 서비스에 할인 계산 기능을 추가하는 풀 리퀘스트를 제출했습니다. 테스트는 통과했고 변경 사항도 많지 않았습니다. 리뷰어는 2분 만에 "괜찮습니다"라고 승인했습니다. 3개월 후, 한 팀원이 동일한 기능을 수정해야 했는데, 가격 책정 규칙, 반올림, 데이터베이스 접근이 한 곳에 뒤섞여 있는 것을 발견했습니다. 누구도 이것이 허용되는 방식인지 확신할 수 없었습니다.

이는 예시 시나리오일 뿐, 실제로 발생한 사건은 아닙니다. 동료 코드 검토가 학습 활동으로서 제대로 기능할 때 어떤 결과물을 만들어내야 하는지를 보여줍니다. 즉, 검토자는 타당한 변경 사항을 파악하고, 아직 버그는 아니지만 우려되는 부분을 찾아내어 작성자가 조치를 취할 수 있도록 설명할 수 있어야 합니다.

이 가이드는 엔지니어링 지원 리더 및 엔지니어링 관리자를 위한 것입니다. 설계 방법을 보여줍니다. 코드 검토 연습 검토자들이 대기열에서 알아차리기를 바라는 대신, 의도적으로 해당 기술을 연마해야 합니다. 이 과정에서는 성능 문제, 진단해야 할 격차, 준비 및 연습 구조, 실제 사례, 그리고 해당 기술이 실제 검토에 적용되는지 확인하는 방법 등을 다룹니다. 모든 사례, 결함 및 기준을 사용하기 전에 선임 엔지니어의 검증을 받으십시오.

코드 리뷰 연습이란 무엇인가요?

코드 리뷰 연습은 개발자가 미리 준비된 변경 사항을 검토하고, 발견한 내용과 그 중요성을 설명하며, 그 설명의 질에 대한 피드백을 받는 구조화된 실습 과제입니다. 이는 팀에서 매일 하는 리뷰와는 다릅니다. 변경 사항은 사전에 선택되고, 우려 사항도 알려져 있으며, 목표는 변경 사항을 배포하는 것이 아니라 리뷰어의 역량을 향상시키는 것입니다.

빠른 사실

1. 성능 문제를 설명하세요

먼저, 검토자가 변경 사항을 발견하고, 그 문제점이 무엇인지, 왜 중요한지, 그리고 작성자가 어떻게 개선할 수 있는지를 한 문장으로 요약하여 설명하는 것부터 시작하세요. 여기서 중요한 단어는 "설명한다"입니다. 문제점을 발견하는 것은 절반의 능력입니다. 하지만 다른 관점을 가진 동료가 이해하고, 고려하고, 조치를 취할 수 있도록 명확하게 설명하는 것이 나머지 절반의 능력입니다.

최신 코드 리뷰에 대한 연구는 버그 찾기를 넘어선 관점을 제시합니다. 마이크로소프트에서 진행된 한 연구에서 바첼리와 버드는 개발자와 관리자를 관찰, 인터뷰, 설문 조사했습니다. 그 결과, 결함 발견이 여전히 리뷰의 주요 동기였지만, 리뷰의 목적은 예상보다 결함 발견에 덜 집중되어 있다는 것을 발견했습니다. 리뷰는 지식 공유, 팀 인식 제고, 대안 제시 등 다양한 이점을 제공했으며, 연구진은 코드와 변경 사항에 대한 이해를 리뷰의 핵심 요소로 꼽았습니다.바첼리와 버드, ICSE 2013이는 한 회사의 팀들을 대상으로 한 연구이므로, 이를 참고하여 여러분의 팀에 적용하는 수치가 아니라 이해를 바탕으로 디자인해야 한다는 점을 강조하는 근거로 활용하세요.

구글이 공개한 코드 검토 기준도 같은 맥락입니다. 검토자에게 코드의 전반적인 상태를 확실히 개선하는 변경 사항이라면 완벽하지 않더라도 승인하는 것을 우선시하라고 지시하고 있으며, 코드 검토를 통해 개발자가 새로운 것을 배울 수 있으므로 학습에 도움이 되는 의견은 환영한다고 명시하고 있습니다.구글 엔지니어링 사례두 자료 모두 검토를 판단이 이루어지고 전달되는 곳으로 설명합니다. 여러분의 연습은 바로 이러한 점을 되새겨야 합니다.

2. 학습 및 맥락 격차를 진단합니다.

현재 수강 중인 프로그램에서 연습하고 평가하는 내용과 해당 과제를 비교해 보세요.

1. 현재의 실무는 실제 과제를 활용하고 있는가? 새로운 코드 리뷰어가 스타일 가이드를 읽고 실제 풀 리퀘스트를 검토하는 방식으로 학습한다면, 실수를 해도 안전한 곳이 없는 실제 작업 환경에서 연습하게 됩니다. 만약 평가가 코드 리뷰 예절에 대한 퀴즈라면, 규칙을 암기한 정도만 측정할 뿐, 변경 사항에 규칙을 적용하는 능력은 측정하지 못하게 됩니다.
2. 인지적 요구 사항은 무엇입니까? 개정된 블룸의 분류 체계에서 디자인의 타당성을 판단하고 장단점을 비교하는 것은 분석 및 평가 단계에 해당하며, 더 나은 구조를 제안하는 것은 창조 단계에 해당합니다. 만약 여러분의 연습 문제가 단순히 "이 코드는 무슨 일을 하는가?"라는 질문만 한다면, 이해 단계에서 멈추게 됩니다. 저희 가이드에서는 이러한 문제를 해결하기 위해 노력합니다. 학습 활동을 블룸의 분류 체계에 맞추기 활동에 맞는 레벨을 선택하는 방법을 보여줍니다.
3. 실력 외에 다른 요인이 방해가 되는 건가요? 검토 시간, 도구, 담당자 및 팀 규범을 확인하세요. 검토자가 풀 리퀘스트당 5분밖에 주어지지 않는다면, 제대로 된 검토 의견을 얻기는 어렵습니다. 작성자가 모든 의견을 비판으로 받아들인다면, 검토자는 결국 아무런 언급도 하지 않을 정도로 완화된 의견을 제시하게 될 것입니다. 이러한 원인을 해결 가능한 담당자에게 보고하세요.

3. 디자인 준비, 연습 및 피드백

각 단계에 별도의 역할을 부여하세요.

예비. 검토자가 검토를 시작하기 전에 필요한 사항을 확인하세요. 팀의 검토 체크리스트, 검토에 사용되는 설계 원칙, 그리고 툴링에서 변경 사항(diff)을 읽는 방법 등을 알려주십시오. 이 과정은 검토자가 스스로 속도를 조절하며 간결하게 진행하도록 하세요. 리콜 체크는 사전 요구 사항만 확인하는 것이며, 검토자가 검토 자격을 갖추었다는 증거는 아닙니다.

연습. 다양한 유형의 문제점을 몇 가지 미리 설정해 두세요. 예를 들어, 정확성 버그, 서두 예시에서처럼 책임이 혼합된 유지보수성 문제, 불명확한 이름이나 누락된 테스트, 그리고 정상적인 코드 등이 있습니다. 리뷰어에게 남길 코멘트를 작성하고, 문제점의 순위를 매기고, 추가적으로 필요한 정보가 무엇인지 물어보세요. CodeRefinery의 실습 강의에서 이 과정을 확인할 수 있습니다. 참가자들이 작은 오타와 큰 오류가 포함된 풀 리퀘스트를 제출하고, 동료처럼 리뷰하는 방식입니다.CodeRefinery, 코드 리뷰 연습하기). 자신만의 코드베이스를 기반으로 구축하여 규칙과 장단점을 실제로 적용해 보세요.

피드백. 검토자가 내린 결정과 연결하세요. "반올림 문제를 발견했지만 어떤 입력값이 문제를 일으키는지 언급하지 않고 '이건 잘못된 것 같다'라고 댓글을 달았습니다."와 같은 설명이 "4개 중 2개를 찾았습니다."보다 더 유용합니다.

실시간 입력 방식인가요, 아니면 비동기식 검토 방식인가요? 실시간 의견 수렴은 문제가 모호할 때 가장 큰 가치를 제공하며, 검토자는 선임 엔지니어가 왜 해당 문제를 제기하거나 무시하는지 설명하는 것을 들으면서 배울 수 있습니다. 비동기 검토는 주석이 달린 전문가 검토와 의견을 비교하는 데 충분합니다.

4. 현실적인 예를 통해 살펴보세요

예시입니다. 엔지니어링 관리자는 사용 전에 사례와 답변 기준을 검증해야 합니다.

경우. 변경 사항은 결제 서비스에 할인 계산 기능을 추가합니다. 이 기능은 테스트를 통과했습니다. 하나의 함수 내에서 백분율 할인과 고정 할인을 적용하고, 결과를 반올림하고, 데이터베이스에 저장하고, 이벤트를 전송합니다. 단일 백분율 할인에 대한 테스트만 포함되어 있습니다.

그 임무. 검토자는 자신이 남길 의견을 작성하고, 우려 사항을 순위별로 정리하며, 승인하기 전에 알아야 할 사항을 명시합니다.

첫 시도입니다. "괜찮아 보이네요, 테스트는 통과했어요. 혹시 나눠서 처리하는 건 어떨까요?" 검토자는 무언가를 발견했지만, 무엇인지, 왜 중요한지, 어떻게 해야 하는지에 대해서는 언급하지 않았습니다. 따라서 작성자는 이에 대해 조치를 취할 수 없습니다.

피드백 후 다시 시도하세요. 진행자는 다음과 같은 질문을 합니다. 이 기능에 대한 향후 변경으로 인해 어떤 문제가 발생할 위험이 있습니까? 승인하기 전에 작성자에게 어떤 내용을 추가해 달라고 요청하시겠습니까? 재시도 단계에서는 각 우려 사항에 대해 구체적인 의견과 함께 이유 및 제안을 제시하도록 요청합니다.

좀 더 나은 시도였습니다. "해당 함수는 두 가지 유형의 할인을 적용하고, 반올림하고, 저장한 후 이벤트를 발생시키므로, 반올림 방식이 변경되면 저장되는 값과 이벤트 발생 결과가 동시에 바뀔 수 있습니다. 가격 책정 규칙을 별도의 함수로 분리하여 독립적으로 테스트할 수 있도록 수정해 주시면 좋겠습니다. 현재 테스트는 백분율 할인만 다루고 있습니다. 고정 할인과 총액이 0이 되는 주문에 대한 테스트를 추가해 주시면 좋겠습니다. 총액이 0일 때 이벤트가 발생하도록 의도된 것인지 확실하지 않으므로, 함수 작성자에게 문의해 주시기 바랍니다." 이 댓글은 우려 사항을 명확히 제시하고, 그 이유를 설명하며, 구체적인 제안을 하고, 검토자가 무엇을 모르는지 밝히고 있습니다.

5. 역량을 평가하고 이전 계획을 수립합니다.

역량의 증거는 평가자가 접하지 못한 새로운 변경 사항에 대한 성과입니다. 조사 결과의 정확성과 설명의 유용성을 점수로 매기십시오. 간단한 평가 기준표는 각 기준에 대해 0에서 2까지의 척도를 사용합니다.

평가 기준: 0은 부재 또는 근거 없음, 1은 관련 누락이 있는 부분적 충족, 2는 합의된 기준에 따라 완전하고 타당성 있는 충족을 의미합니다. 데이터 손실 위험이 있는 변경 승인과 같은 중요한 오류는 별도로 정의하여, 높은 전체 점수가 중요한 오류를 가리지 않도록 하십시오. 엔지니어링 관리자와 협의하여 평가 기준을 조정하십시오. 이 평가 기준표는 시작 단계의 제안일 뿐, 검증된 준비 표준이 아닙니다. 점수 산정 근거에 대한 자세한 내용은 가이드를 참조하십시오. 유용한 피드백을 제공하는 상호작용적 연습 설계.

전이 계획을 세우세요. 연습 후 몇 주 뒤 동일한 기준을 사용하여 검토자의 실제 검토 샘플을 확인하세요. 교육 전 기준선과 비교하고 대상 집단과 시기를 사전에 정의하세요. 연습의 효과를 인정하기 전에 새로운 검토 도구 도입이나 인력 변동과 같이 같은 기간 동안 발생한 다른 변화도 고려하세요.

6. AhaSlides를 사용하여 실시간으로 또는 자기 주도 학습 방식으로 연습을 진행하세요.

워크숍에서 이 연습을 진행하거나 검토자들이 스스로 풀어보도록 할 수 있습니다. 실시간 세션에서는 준비된 변경 사항을 보여주고 토론을 위해 인터랙티브 슬라이드를 활용하세요.

1. 답변 선택 "어떤 우려 사항을 먼저 제기하시겠습니까?"라는 질문에 대해, 제시된 우려 사항들을 선택지로 보여주세요. 자신의 순위를 공개하기 전에 선택지별 순위 분포를 보여주세요.
2. 오픈 종료 "나라면 남길 댓글을 작성해 보세요."와 같은 질문에 대해, 검토자들은 다른 사람들이 쓴 글과 비교해 볼 수 있는데, 바로 이 부분에서 설명 능력이 드러납니다.
3. 평가 척도 "이 문제가 얼마나 심각한가?"라는 질문에 답함으로써, 그룹 구성원들이 판단의 차이를 파악하고 그 이유에 대해 논의할 수 있도록 합니다.

참석할 수 없는 검토자의 경우, 각 답변 후 전문가의 주석이 달린 검토 내용을 보여주는 동일한 순서를 자율 학습 방식으로 활용할 수 있습니다. 코드 실행, 통합 또는 AI 기능에 대한 모든 주장은 직접 테스트해 보기 전까지는 확인되지 않은 것으로 간주하십시오.

AI가 작성한 코드로 리뷰어를 학습시키는 경우, 관련 가이드를 참조하세요. AI 기반 코드 검토 교육저 글은 생성된 결과물을 감사하는 것에 관한 것이고, 이 글은 사람들이 서로의 작업을 검토하고 그 결과를 설명하는 방법에 관한 것입니다.

남아 있을 수 있는 제약 조건

• 복습 시간입니다. 사려 깊은 댓글은 "LGTM"이라는 간단한 답변보다 시간이 더 오래 걸리지만, 마감일은 짧은 답변을 선호하게 만듭니다.
• 팀 규범. 피드백이 개인적인 비판으로 받아들여지면 검토자는 의견을 완화하거나 의견을 철회할 것입니다.
• 사건 처리 범위. 한 가지 사례를 통해 몇 가지 우려 사항이 드러납니다. 점수만으로는 평가자의 판단을 전반적으로 설명할 수 없습니다.
• 이전. 워크숍에서의 성과는 혼잡한 대기열에서의 성과와 다르므로 실제 사용자 후기도 확인하세요.

이러한 사항들을 스폰서에게 미리 알리고 별도의 수정 계획을 세우세요. 연습은 검토자가 더 잘 이해하고 설명할 수 있도록 도와줍니다. 하지만 연습 자체가 시간이나 기준을 만들어내는 것은 아닙니다.

자주하는 질문

코드 리뷰 연습이란 무엇인가요?

이러한 연습 과제는 개발자가 알려진 문제점이 있는 변경 사항을 검토하고, 남길 의견을 작성하고, 정확성과 유용성에 대한 피드백을 받는 방식으로 진행됩니다. 목표는 변경 사항을 배포하는 것이 아니라 검토자의 역량을 향상시키는 것입니다.

리뷰어의 판단력이 향상되었는지 어떻게 평가하나요?

이전에 보지 못했던 새로운 변경 사항을 제시하고, 합의된 기준에 따라 결과와 설명을 평가합니다. 그런 다음 몇 주 후 실제 리뷰 샘플을 확인합니다. 리뷰 규칙에 대한 퀴즈는 필수 요건 충족 여부만 확인합니다.

동료 코드 리뷰는 주로 버그를 찾는 것인가요?

결함을 찾는 것이 여전히 주요 동기이지만, 마이크로소프트의 한 연구에 따르면 리뷰는 예상보다 결함 발견에 집중하기보다는 지식 공유와 팀 인식 제고에 더 중점을 두는 것으로 나타났습니다. 결함 개수뿐만 아니라 설명과 이해도를 보상하는 리뷰 방식을 설계해 보세요.

어디서 시작하나요

팀에서 자주 검토하는 변경 사항 유형 하나를 선택하세요. 성과 평가서를 작성하고, 선임 엔지니어에게 세네 가지 주요 문제점을 포함한 변경 사항 하나를 준비해 달라고 요청하세요. 그리고 0에서 2까지의 척도와 주요 오류 목록이 포함된 세 가지 기준의 평가표를 작성하세요. 소규모 그룹으로 시범 운영한 후, 다음 실제 검토에서 얻은 결과를 기준선과 비교해 보세요.

팀원들과 함께 실시간으로 검토 활동을 진행하고, 이후에도 자율 학습 방식으로 재사용하는 방법을 알아보려면 AhaSlides를 살펴보세요.