원문 링크: Better Code Review: Part One – RetailMeNot Engineering – Medium

Self-Review

코드 리뷰는 소프트웨어 엔지니어링에 필수적인 부분으로, 혼자 작업하지 않는 한 일상적인 소프트웨어 개발 업무의 한 부분이 될 가능성이 높습니다. 코드 리뷰는 때때로 논쟁을 유발하며, 그것은 치아 신경 치료만큼 재밌지만(?) 그럴 필요는 없습니다. 3부로 구성된 이 시리즈를 통해, 제 경험에서 얻은 몇 가지 팁을 제시하여 여러분의 코드가 좀 더 생산적이고 덜 부담스러운 방식으로 검토되고, 또 검토할 수 있도록 도울 것입니다. 첫째는, 자기-검토입니다. 다른 사람이 코드를 검토하기 전에 먼저 자기-검토 항목을 작성함으로써 버그를 조기에 발견하고, 보다 성공적인 기술 토론을 위해 준비할 수 있습니다.

2013년 Microsoft는 “왜 코드 리뷰를 해야 하고, 코드 리뷰를 통해 얻는 가장 빈번한 결과는 무엇이며, 효과적인 코드 리뷰 방법은 무엇인지” 알아내기 위한 내부 연구를 수행했습니다. 설문에 참여한 대부분의 사람들은 버그 발견을 코드 리뷰의 주요 동기로 응답했지만, 실제로 코드 결함을 보고한 응답은 14%에 불과하였습니다. 이 연구에서 밝혀진 코드 리뷰의 주요 성과는 지식 전파와 팀 의식 향상 그리고 문제에 대한 해결책 모색이었습니다. 이 정보를 바탕으로 위와 같은 성과를 이끌어 낼 수 있도록 검사자와 피검사자를 변화시킬 수 있는 방법은 무엇일까요?

코드 리뷰 프로세스는 여러분이 pull request를 생성할 때 시작하는 것이 아니라, 공유 코드 베이스에 병합할 코드를 작성할 때 시작합니다. 관련 당사자들 모두에게 최선의 프로세스를 보장하기 위해 pull request를 생성 전에 수행해야 하는 몇 가지 의무 점검 사항이 있습니다. 저는 먼저 자기-검토를 수행함으로써 더 좋고 강력한 코드를 만들 수 있다고 믿고 있습니다.

three steps to self-review:

1. Run it
2. Read it
3. Document it

Run it

뻔한 이야기로 들릴 수도 있지만, 코드를 실행해 보세요. 간단한 문자열 변경의 경우에도, 반드시 코드를 실행해 봐야 합니다. 검토가 필요한 코드가 동작하지 않으면 개발자와 QE(QA Engineer)의 시간이 낭비됩니다. 매우 똑똑한 개발자가 작성한 좋은 코드에서도 잘못 입력된 세미콜론이나, 뒤 바뀐 boolean 조건 때문에 충돌이 발생할 수 있습니다. PR을 생성하기 전에 항상 확인하는 것이 좋습니다. 하는 김에, Linter를 이용하는 것도 좋습니다. Annyce Davis가 작성한 셀프-리뷰를 자동화하기 위한 방법이라는 아주 멋진 게시물을 읽어보세요. 검사자가 내용에 집중할 수 있도록 코드가 팀에서 합의한 스타일 가이드라인을 준수하는지 확인하세요. Microsoft의 연구에 따르면 코드 스타일에 대한 반복적인 언급이 기술적인 논의(토론)의 가치를 감소시키고 스트레스의 원인이 된다는것을 발견했습니다. 되도록 검사자 피검사자 모두 이를 준수해야 합니다.

알아보기 어렵겠지만, if 문에서 실수로 변수 하나를 제거했더니 조건 문의 논리가 반대가 되었습니다. 단순히 코드를 읽는 것보다 코드를 실행해 보는 것이 쉽게 오류를 발견할 수 있는 방법 중 하나입니다.

Read it

PR 요청을 생성하기 전에 코드의 변경사항을 비교(diff) 한 후 개발과정에서 수행한 논리적 절차가 명확한지 스스로에게 질문해 보세요. 작성한 코드가 오직 일감에 관련된 문제만을 해결하고 있나요? 만약 변경 사항이 일감의 범위를 넘어서는 경우에는 해결해야 할 문제에 대해서만 초점을 유지하기 위해 개별 일감으로 분리하는 것이 좋습니다. 변수의 이름이 의미에 맞게 작성되었나요? yesOrNo라는 boolean 변수의 목적을 유추하기 어렵습니다. 피검사자로서 여러분의 역할은 코드 리뷰에 대한 기술 토론을 촉진시키기 충분한 컨텍스트를 제공해야 하는 것이므로, 코드에 얼마만큼을 추가하고 보완해야 할지 결정해야 합니다.

위의 “inputSteam”과 같은 오타는 지적하기 번거로운(귀찮은) 부분이 있습니다. 비교(diff)를 통해 자신만의 문제를 찾고 수정하는 것이 가장 좋습니다.

Document it

진정한 자체-문서화 코드는 극히 드문 경우입니다. 대부분의 코드에는 여러 가지 형태의 별도의 문서가 존재합니다. 커밋 메시지처럼 간단할 수도 있고 (일감 번호가 표기되어 있지 않을 수도 있고) 혹은 전체 javadoc 처럼 복잡할 수도 있습니다. 테스트 코드 역시 코드가 동작하는 방식과 사용 방법을 문서화할 수 있는 매우 좋은 방법입니다. 코드가 의도한 대로 성공하고 실패하는지 테스트하세요. PR 요청을 만들 때 검사자를 위한 컨텍스트 그리고 코드를 개발할 때의 의사 결정 과정을 설명하는 코멘트를 제공하세요. PR 요청을 생성할 때 검사자를 위해 여러분이 코드를 작성 시 의사 결정 과정을 설명하는 코멘트를 제공하세요. 아마도 언젠가는 다른 사람이 여러분의 코드를 유지 관리해야 합니다. 코드가 어떤 이유로 왜 이렇게 동작하는지 도움이 될 수 있도록 최신 문서를 작성해야 합니다.

위의 반복적인 코드에서, 몇 줄의 명확한 설명의 주석이 가독성을 높입니다.

코드를 실행하고, 읽고, 문서화하는 데 시간을 투자하는 것은 코드 리뷰 프로세스에서 피검사자의 성실함 중 한 부분입니다. PR 요청 전에 작은 버그나 스타일 이슈를 미리 해결해 두면 검사자가 좀 더 심도 있는 기술 토론에 집중할 수 있고, 논리적으로 명확하고 가독성 높은 코드를 통해 질문에 답하는 시간을 단축시킬 수 있습니다. 코드를 문서화하여 의사 결정 프로세스를 이해하고 향후 코드를 유지하는 데 필요한 컨텍스트를 제공하세요.