코드 가독성에 대해 – 5. 리뷰와 정리

들어가며

안녕하세요. 커뮤니케이션 앱 LINE의 Android 클라이언트 팀 Ishikawa입니다. 이 글은 ‘코드 가독성에 관한 프레젠테이션’을 소개하는 비정기 연재 블로그의 다섯 번째 글(1편2편3편4편)이자 마지막 글입니다. 이번 글에서는 8장 ‘리뷰’에 관해 설명한 뒤 본 연재의 요점을 정리하겠습니다. 

 

8장: 리뷰

코드 리뷰를 지속 가능한 소프트웨어 개발을 위한 수단으로 사용하여 코드의 가독성과 견고함을 향상시키는 것은 효과적인 방법입니다. 코드를 리뷰하면 해당 코드의 품질이 향상되는 것뿐 아니라 정보가 공유되면서 팀 전체의 기술력이 향상되는 효과도 있습니다. 다만, 코드 리뷰 자체가 개발 과정에서 병목 구간이 되지 않도록 조심해야 하는데요. 본 장에서는 코드 리뷰할 때 주의해야 할 점에 관해서 리뷰를 받는 쪽과 하는 쪽으로 나누어 설명하겠습니다.

참고. 이 글에서는 GitHub을 사용해 코드 리뷰를 진행한다고 가정했는데요. 현재 GitLab이나 Gerrit 등 다른 도구를 사용하고 있다면, PR(풀 리퀘스트)을 각각 ‘머지 리퀘스트’나 ‘체인지’ 등으로 적절하게 바꿔서 읽어주시기 바랍니다. 

 

1.  코드 리뷰 요청

 

1-A: PR과 커밋은 되도록 구조적으로 작게 생성하기

PR과 커밋의 의도가 명확하면 코드 리뷰를 효율적으로 진행할 수 있기 때문에 PR과 커밋은 구조적으로 생성해야 합니다. 예를 들어 이름을 바꾸는 것과 같은 단순하고 광범위한 변경과, 로직을 바꾸는 것과 같은 복잡하고 한정적인 범위의 변경이 하나의 커밋에 함께 포함되어 있으면 리뷰어가 커밋을 이해하는 데 시간이 걸립니다. 따라서 리뷰를 요청하기 전에 커밋을 분할하거나 각 커밋의 책임 범위를 명확히 하고 커밋 간의 흐름을 정렬해서 명시적으로 만드는 게 좋습니다. 

또한 PR과 커밋의 규모가 크면 개발 속도를 저하시키는 원인이 될 수 있습니다. PR의 규모가 크면 리뷰하는 데 시간이 걸릴 뿐 아니라 만약 수정해야 할 경우 많은 범위를 다시 작업해야 할 수도 있습니다. 따라서 1주일에 걸쳐 규모가 큰 하나의 PR를 만드는 것보다는 작업을 여러 개의 PR로 분할하는 게 좋습니다. PR을 분할하려면 일시적으로 제대로 동작하지 않는 코드를 머지해야 할 수도 있습니다. 예를 들어 다른 코드의 부품이 되는 모델이나 유틸리티를 먼저 만든다거나, 의존성을 나타내기 위한 골격 구현을 만드는 경우인데요. 이럴 때는 향후 구현 계획을 TO-DO 코멘트나 PR 코멘트로 명시해 놓는 게 좋습니다.

 

1-B: 리뷰 코멘트의 의도와 이유를 이해하기 

리뷰 코멘트를 PR에 반영할 때는 그 코멘트의 의도와 이유를 이해하는 것이 중요합니다. 예를 들어 리뷰어가 코드의 내용을 착각해서 코멘트하거나 코멘트를 통해 질문을 던지는 경우에는 코드가 난해해서 그런 오해나 의문을 초래한 것은 아닌지 생각해 봐야 합니다. 그럴 땐 코드를 변경해서 리뷰 코멘트에 답변하거나, 또는 경우에 따라서는 답변 코멘트를 추가하는 것만으로도 오해와 의문을 해소할 수도 있습니다. 

 

2. 코드 리뷰 진행

 

2-A: 리뷰 거부하기

코드 리뷰를 원활하게 진행하기 위해 리뷰 요청을 받은 시점부터 첫 회신까지 걸리는 목표 시간을 프로젝트에서 정의해 두면 좋습니다. 목표 시간을 설정하는 예로 ‘리뷰 요청을 받은 시점부터 다음 근무일의 같은 시각까지 회신한다’와 같은 것을 들 수 있습니다. 여기서 이 목표 시간은 ‘회신’까지 걸리는 시간이지 ‘리뷰 진행’까지가 아닌 것에 주목해야 합니다. 예를 들어 먼저 진행해야 하는 다른 작업 때문에 리뷰를 할 수 없을 때는 ‘현재 리뷰 불가능’ 또는 ‘리뷰가 늦어짐’이라고 회신해야 합니다. 그렇게 해야 리뷰 요청자가 다음 행동을 선택할 수 있는데요. 만약 시급한 PR이라면 다른 개발자에게 리뷰를 요청할 수 있고, 그렇지 않다면 그냥 기다리는 것을 선택할 수도 있습니다.  

만약 PR의 규모가 크거나 설계에 근본적인 결함이 있는 경우, 그대로 리뷰를 진행하면 막대한 시간을 허비하게 될 가능성이 있습니다. 그럴 때는 자세하게 리뷰하지 말고 일단 PR를 닫도록 하는 것도 하나의 방법입니다. 그 후에 어떻게 PR를 분할하면 좋을지, 혹은 어떻게 설계하면 좋을지를 채팅이나 페어 프로그래밍 등을 통해 지원하는 것도 좋습니다. 이렇게 리뷰를 거부함으로써 결과적으로 생산성을 향상시킬 수 있는 경우가 많이 있습니다.

 

2-B: 무엇을 코멘트해야 하는가

리뷰어가 확인하고 코멘트해야 하는 사항은 아래와 같이 정리할 수 있습니다. 

  • 코딩 스타일과 규약, 언어 혹은 플랫폼에서 사용하는 관용구
  • 테스트의 범위와 타당성
  • 본 연재에서 설명한 내용 전체: 원칙과 명명, 주석, 상태, 절차, 의존성
  • 그밖에 리뷰하면서 발견한 모든 문제

문제점을 지적할 때 수정 방법까지 코멘트할 것인지에 대해서는 한 번 생각해봐야 합니다. 예를 들어 리뷰를 요청한 쪽에서 수정 방법을 생각하도록 정한다면, 코드 리뷰의 부담을 양쪽에 균형 있게 나누면서 상호 기술력이 향상되는 기회가 될 수도 있습니다. 상황에 따라 수정 내용 제시, 문제점 지적, 질문으로 적절히 나눠서 대응하면 좋을 것입니다. 

 

본 연재의 요점 정리

총 5번의 연재를 통해 전체 8장으로 구성했던 프레젠테이션의 개요를 설명했습니다. 각 장의 요점은 아래와 같습니다.

1장: 도입과 원칙

2장: 명명

  • 이름으로 대상이 무엇인지, 무엇을 하는지 나타낸다.
  • 문법과 단어 선택에 주의한다.

3장: 주석

  • 주석은 코드의 이해를 돕고 오해를 방지하기 위한 것이다.
  • 문서화 주석에는 요약을 넣는다.

4장: 상태

  • 비직교(non-orthogonal) 관계를 배제한다.
  • 좀 더 단순한 상태 변환(불변 혹은 단 방향)을 사용한다.

5장: 절차

  • 절차의 책임 범위(부작용, 반환값)를 명시적으로 정한다.
  • 정의 기반(definition based) 프로그래밍으로 흐름을 나타낸다.

6장, 7장: 의존성

  • 내용 결합과 공통 결합, 제어 결합을 완화한다.
  • 의존성의 순환과 중복을 피한다.
  • 명시적인 의존성을 사용한다.

8장: 리뷰

  • PR과 커밋은 구조적으로 작게 생성한다.
  • 리뷰 코멘트의 의도를 파악한다.
  • 리뷰어로서 무리하게 리뷰하지 않는다.

이것으로 코드 가독성에 관한 프레젠테이션을 소개하는 연재를 마치겠습니다. 프레젠이션에서는 지면 관계상 이번 연재에 싣지 못한 이슈와 구체적인 사례도 다루고 있으니 참고하시기 바랍니다. 긴 연재 읽어주셔서 감사합니다. 

Related Post