Google의 코드 리뷰 기준을 작은 변경에 적용하기

코드 리뷰를 기다리는 동안 작성자는 후속 작업을 진행할 수 있지만, 검토 중인 설계가 바뀌면 그 작업도 다시 고쳐야 합니다. 리뷰어는 발견한 문제 중 이번 변경에서 반드시 해결할 것과 선택적으로 개선할 것을 구분해야 합니다.

Google의 Engineering Practices에서는 변경 후의 코드가 이전보다 유지보수하기 쉬워지는지를 리뷰 기준으로 삼습니다. 여기서 코드 건강은 다음 개발자가 동작을 이해하고, 수정하고, 검증할 수 있는 정도를 뜻합니다. 리뷰어는 현재 작성자뿐 아니라 나중에 이 코드를 읽을 사람도 고려해야 합니다. 개인의 선호와 팀이 합의한 유지보수 기준을 구분하면 작은 변경을 어디서 마칠지도 정하기 쉬워집니다.

변경 목적을 알고 설계 읽기

리뷰어는 변경한 줄을 위에서부터 읽기 전에 설명문을 확인합니다. 작성자는 무엇을 고쳤는지, 왜 필요한지, 사용자가 어떤 차이를 보게 되는지 설명해야 합니다. 목적을 모르면 코드가 그 목적에 맞는지도 판단하기 어렵습니다.

주문 상태를 바꾸는 API를 검토한다고 가정해보겠습니다. 같은 주문에 요청이 두 번 들어왔을 때 상태 변경과 이력 저장이 함께 처리되는지 먼저 봅니다. 코드가 짧거나 스타일 검사를 통과해도 중복 처리 문제는 남을 수 있습니다.

설계가 맞는지 확인한 뒤 실제 동작, 불필요한 복잡도, 테스트, 이름, 주석, 문서를 봅니다. 주변 코드도 필요한 만큼 읽습니다. 추가된 몇 줄이 기존 함수의 가정과 충돌할 수 있기 때문입니다.

직접 작성한 주문 처리 의사 코드입니다. 주문 상태와 이력을 함께 저장해야 하는 조건을 리뷰 코멘트로 표시했습니다.

수정이 필요한 이유와 제안의 범위

리뷰 코멘트에는 문제와 이유를 함께 적습니다. 작성자가 어떤 조건을 놓쳤고 무엇을 수정해야 하는지 알 수 있어야 합니다. “이 구조가 별로입니다”보다 “이 함수가 저장과 알림을 함께 처리해 알림 실패 시 재시도 범위를 정하기 어렵습니다”가 수정 방향을 판단하기 쉽습니다.

승인을 막아야 하는 문제와 선택적인 개선도 구분합니다. 사용자 오류를 만들거나 유지보수를 어렵게 하는 문제는 해결해야 합니다. 의미가 같은 이름 중 하나를 선호하거나 문장을 조금 다듬는 제안은 필수 수정으로 다루지 않아도 됩니다. 팀에서 합의한 스타일 규칙이 있다면 그 규칙을 먼저 적용합니다.

리뷰 대화에서는 설명이 충분했어도 몇 달 뒤 코드를 읽는 사람은 그 대화를 모를 수 있습니다. 이해하기 어려웠던 부분은 코드 자체를 단순하게 만들거나, 코드만으로 알 수 없는 결정 이유를 주석으로 남겨주세요. 다음 개발자가 코드와 주석만으로 같은 결정 이유를 확인할 수 있어야 합니다.

하나의 목적을 담은 변경

Google의 작은 변경 안내에서는 하나의 목적을 가진 독립적인 변경을 권합니다. 한 가지 동작을 바꾸고 관련 테스트를 함께 넣으며, 적용한 뒤에도 시스템이 동작해야 합니다. 함수 이동, 전체 포맷 변경, 기능 추가를 한꺼번에 섞으면 실제 동작 차이를 찾기 어렵습니다.

로그인 오류를 고치는 PR이라면 오류 처리와 회귀 테스트를 함께 보내고, 관련 없는 파일 정리는 따로 처리할 수 있습니다. 반대로 새 함수를 만들면서 호출하는 코드와 테스트를 다음 PR로 미루면 첫 변경의 의미를 확인하기 어렵습니다. 분할 후에도 각 변경을 검토할 수 있어야 합니다.

작성자는 설명문에 변경 전후의 차이를 적습니다. “로그인 버그 수정”보다 “만료된 세션으로 접근하면 빈 화면 대신 로그인 화면을 표시”가 구체적입니다. 확인한 동작과 남은 제한도 함께 적으면 리뷰어가 다시 조사할 범위를 줄일 수 있습니다.

리뷰가 늦어질 때 생기는 후속 작업

리뷰가 늦어져 작성자가 검토 중인 코드를 기반으로 후속 작업을 시작한 경우를 생각해보겠습니다. 나중에 설계 문제가 발견되면 후속 변경까지 고쳐야 합니다. 전체를 바로 읽을 수 없더라도 큰 문제를 먼저 전달하거나 검토 가능한 시간을 알려주면 작업 순서를 조정할 수 있습니다.

일정이 촉박해도 동작과 설계의 문제는 해결해야 합니다. 리뷰어가 선택적인 표현 수정과 승인에 필요한 수정을 구분해 전달하면 작성자는 먼저 고칠 부분을 알 수 있습니다. 같은 코드를 읽어도 작성자와 리뷰어가 고려한 조건은 다를 수 있습니다. 코멘트에 이유를 적으면 서로 어떤 조건을 고려했는지 비교하고, 이번 변경에서 수정할 범위를 정할 수 있습니다.