좋은 코드 리뷰를 만드는 7가지 원칙
AI 시대 개발자가 반드시 알아야 할 코드 리뷰 방법
ICT의 확산으로 SW 비중이 커지고 비지니스 시장이 더욱 복잡해지며 변화에 맞추는 개발이 필요해졌습니다. 좋은 설계 없이 기능만 누적될 경우 기술 부채가 폭증된다는 것이 입증되며 이후의 일정 지연과 비용 폭탄을 막기위한 초반 품질 투자의 중요성이 대두되고 있습니다. 이제는 단순히 기능 구현에 그치지 않고, 유지보수 비용을 줄이고 품질을 높일 수 있는 코드가 요구됩니다.
코드 리뷰는 단순한 버그 예방 절차가 아닙니다. 자동화 테스트와 AI가 많은 부분을 보완하지만, 설계 오류나 맥락까지는 해결하기 어렵습니다. 동료 검토를 통한 코드 리뷰는 이를 보완하는 핵심 품질 보증 활동이며, AI 시대에 더욱 강조되는 개발자의 핵심 역량입니다.
코드 리뷰의 목표는 아래와 같습니다.
1. 읽기 쉽고 확장성이 있으며 성능과 보안 겸비할 코드로 품질을 향상
2. 리뷰하는 사람이 배운 것을 팀 전체에 확산시키는 지식 공유
3. 협업, 존중, 멘토링의 문화가 퍼지도록 팀 문화를 강화
좋은 코드 리뷰는 어떤 걸까?
코드 리뷰 노하우
1. 최대한 빠르게 리뷰에 착수하고, 실행 가능한 피드백 위주로 전달하기
PR 요청이 오면 저자는 해당 작업을 마무리하기 위해 리뷰를 기다리는 경우가 많습니다. 따라서 리뷰 리드타임(응답 속도)이 짧을수록 전체 속도가 빨라집니다.
또한 잘한 점, 아쉬운 점, 리뷰 포인트를 본문 첫 코멘트에 직접 써주면 좋습니다. 비효율적이다 라는 단순한 리뷰보다는 대안과 근거, 예시를 주는 연습을 하면 더욱 훌륭한 코드 리뷰를 앞으로도 할 수 있게 됩니다.
“iterrows()는 느려요” 란 말 대신 “iterrows() 대신 itertuples()을 쓰면 10배 빠릅니다. 예시는 이렇게…” 란 식의 피드백은 단순히 지적이 아닌 문제 해결 가이드로, 큰 지지로 돌려 받을 수 있습니다.
2. 먼저 사용자처럼 읽기
코드를 직접 읽기 전에 함수 호출방식 사용 예시를 보는 게 빠릅니다.
함수 인터페이스가 명확하면 코드 본문도 이해하기 쉽습니다.
좋은 코드는 함수 이름, 피라미터 이름만 봐도 스토리가 드러나야 합니다.
3. 고수준에서 저수준으로 피드백을 전달하기
코드 리뷰를 줄 단위에서 시작하면 세부적인 데만 매달리게 됩니다.
먼저 버그, 성능, 보안, 설계와 같은 큰 문제를 살펴보고 마지막 단계에 네이밍, 주석 등의 가독성을 다듬는 것이 효과적입니다.
우선 안티패턴(테스트하기 어려운 구조, 중복 코드, 보안 취약점 등)을 잡고, 성능은 실제 병목이 될 수 있는 부분을 집중적으로 확인합니다.
예를 들어 판다스에서의 `iterrows()` 루프, 데이터베이스의 N+1 쿼리, 불필요한 API 반복 호출 같은 구간은 초기에 발견하는 것이 좋습니다. 성능은 조기 최적화에 집착하기보다는 실제 문제를 유발할 가능성이 높은 부분 위주로 살펴보는 것이 바람직합니다.
- 실무 예시
나쁨: 데이터 전처리 함수 안에서 DB 연결까지 처리함 → 테스트 불가능, 유지보수 악몽.
좋음: DB 연결은 별도 함수/모듈, 전처리 함수는 DataFrame만 받아서 처리.
4. 코드 변경을 제안할때는 필수적인 요소만 진행하기
라운드당 2~3개로, 왜 바꾸는게 좋은지 설명하는 것이 효과적입니다.
예제 코드 제안이 많으면 많을 수록 수용할 수 있는 범위도 줄어듭니다. 범위를 존중하며 PR에 포함된 라인을 중심으로 리뷰하도록 합니다. D등급 코드라면 C등급으로, B등급이라면 A등급으로, 한단계씩만 올리는 것을 목표로 할때 꾸준히 코드 리뷰를 주고받을 수 있습니다.
5. 함수·클래스 경계하기
SRP원칙으로, 함수는 한가지 책임만 가져야 합니다. 여러 일을 동시에 하면 테스트가 불가능해지며 변경시 리스크가 커집니다. 한 함수가 너무 많은 역할을 가지고 있지 않은지 살펴봅니다.
- 실무 예시
파일 읽기, 숫자 파싱, 평균 계산, 출력 → 각각 함수로 쪼개기.
이렇게 하면 average()만 단위 테스트 가능.
6. 테스트와 엣지 케이스 살펴보기
정상 케이스 외에 다양하게 확인해봅시다
0, 음수, None, 빈 리스트, 예외 발생과 같은 엣지 케이스를 생각하도록 합니다. 이 함수가 망가질 수 있는 입력값을 생각해보고 테스트해보세요.
7. 로그 출력 시 보안과 개인정보 노출, 인증·인가 로직 누락 체크하기
비밀번호, 토큰, 개인정보와 같은 민감한 정보는 절대 코드에 직접 하드코딩하면 안 됩니다.
또한 로그 출력 시 개인정보가 노출되거나, 인증·인가 로직이 누락되지 않았는지 항상 확인해야 합니다. 민감 정보가 하드코딩 된 것은 아닌지 리뷰어는 항상 신경써야 합니다.
이렇게 총망라해 정리해 보았지만 실제로 코드 리뷰에 들어가면 생각보다 포인트가 잘 안 떠오르곤 합니다. 그래서 바로 참고할 수 있는 체크리스트를 정리했습니다.
좋은 코드 리뷰 체크리스트
설계 적절성 관점에서 올바른 문제 해결이 가능한가?
사용자 관점에서 인터페이스가 명확한가?
가독성/스타일에서 우리팀이 정한 기준을 준수하는가?
단일 책임 원칙 지켰는가?
테스트 + 엣지 케이스가 충분한가?
성능 병목 현상은 없는가?
보안/개인정보가 안전한가?
피드백은 실행 가능했는가?
긍정 피드백 포함했는가?
개발자 업무 리포트인 BCTO에는 이런 코드 리뷰 활동도 기록해 반영할 수 있는데요.
현재 BCTO 서비스는 개발자 분들이라면 무료로 이용할 수 있도록 운영하고 있습니다.
회원가입 후 자신의 git 데이터만 입력하면 이런 리포트를 받아 볼 수 있습니다.
한 줄의 피드백이 팀 전체를 더 나은 방향으로 바꿉니다. 버그를 잡는 것보다 더 큰 가치는 함께 배우고 성장하는 데 있습니다. 서로를 성장시킨다는 마음으로, 오늘도 좋은 리뷰 화이팅입니다.
- B.CTO(비씨티오)는 개발자의 Git 활동을
자동으로 분석해, 관리자가 쉽게 개발 상황을
파악할 수 있게 해주는 서비스입니다.
