코드 리뷰 프로세스

• 코드 리뷰에서 흔히 발생하는 현상 중 하나는 코드 형식과 스타일 같은 사소한 측면에 대한 집중과 장황한 토론이 이루어지는 반면,
• 중요한 측면들(코드 변경이 의도한 바를 제대로 수행하는지, 성능이 좋은지, 기존 클라이언트에 대한 역호환성이 있는지 등)은 상대적으로 덜 주목받는다는 것입니다.

---

• 아래 피라미드 그림 제공의 목적은 코드 리뷰 중 가장 중요한 부분에 초점을 맞추는 데 도움을 주고, 자동화할 수 있고 해야 하는 부분을 알려주는 것입니다.

---

• 
• 위로 갈수록, 리뷰어의 리뷰 영역보단, 자동화의 영역
• 아래로 갈수록, 리뷰어가 리뷰에 집중해야할 영역
• 아래에서 부터, 위로 올라가면서 설명 해보겠습니다.

---

리뷰 대상 1: API Semantics (API 디자인에 관한 검토)

• 코드 리뷰 시, 가장 중요한 부분

1. API as small as possible, as large as needed?

• 이 질문은 API가 최소한으로 작으면서도 필요한 기능을 모두 수행할 수 있도록 설계되었는지를 평가
• 작고 간결한 API는 이해하고 사용하기 쉬우며, 오류의 여지를 줄이고 유지 관리가 용이
• 반면, 필요한 기능을 충분히 제공하지 않는 API는 확장성이 떨어질 수 있음

1. 작고 간결한 API:
   • API를 작게 유지하는 것은 복잡성을 최소화하고, 사용자가 API를 더 쉽게 이해하고 사용할 수 있도록 함
   • 작은 API는 오류가 발생할 가능성도 줄어들고, 개발 및 유지보수 과정에서 문제를 쉽게 파악하고 해결할 수 있음
   • 예를 들어, 몇 가지 핵심 기능만을 제공하는 API는 그 기능들을 철저히 최적화하고 문제 발생 시 빠르게 대응할 수 있음
2. 필요한 만큼의 크기:
   • 반면, API는 사용자의 요구를 충족시킬 수 있을 만큼 충분히 커야 합니다.
   • 이는 API가 그 목적에 맞게 충분히 유연하고 확장 가능해야 한다는 것을 의미합니다.
   • 예를 들어, 특정 데이터를 처리하고 결과를 반환하는 API가 있을 때,
     • 이 API가 다양한 형태의 데이터를 받아 처리할 수 있는 기능을 포함하고 있어야 사용자의 다양한 요구를 만족시킬 수 있음
3. API 설계의 균형 찾기:
   • 이 원칙은 따라서 API를 너무 간소화시켜 필요한 기능을 제공하지 못하게 되는 것을 방지하면서도, 너무 많은 기능을 추가해 복잡성이 증가하는 것을 피하는 데 중점을 둠
   • 즉, API는 사용자가 필요로 하는 기능을 정확하고 효율적으로 수행할 수 있도록 설계되어야 하며, 동시에 불필요한 기능으로 인한 혼란이나 오류의 가능성을 최소화해야 합니다.

2. Is there one way of doing one thing, not multiple ones?

• API가 단일 기능을 수행하는 데 여러 방법을 제공하지 않고 하나의 명확한 방법만을 제공하는지 검토합니다.
• 이는 API의 일관성, 사용성과 유지보수성을 크게 향상시키는데 중요합니다.
• 여러 방법이 존재하면 사용자는 어떤 방법이 최적인지 결정하기 어려울 수 있습니다.
• 일관성 유지
  • API가 일관된 방법으로 기능을 제공하면, 개발자들은 새로운 기능을 배우거나 기존 기능을 사용할 때 덜 혼란스러워함
  • 예를 들어, 파일을 열고 저장하는 기능이 있다고 할 때, openFile()과 saveFile()과 같이 간단하고 명확한 메소드를 제공하는 것이 효과적
  • 반면에 openFile(), openNewFile(), fileOpen() 등 여러 메소드가 같은 기능을 제공한다면,
    • 개발자는 각 메소드가 어떻게 다른지, 어떤 상황에서 사용해야 하는지를 이해하고 결정해야 하는 부담을 가지게 됨
• 사용자 혼란 방지
  • API에서 하나의 기능을 수행하는 데 여러 방법을 제공하면, 사용자는 이 중에서 어떤 방법이 자신의 요구에 가장 잘 맞는지 결정하기 어려워집니다.
  • 이는 특히 새로운 사용자나 API에 익숙하지 않은 사용자에게 더욱 큰 문제가 될 수 있습니다.
  • 하나의 명확한 방법만 제공하면 사용자는 선택의 고민 없이 바로 해당 방법을 배우고 사용할 수 있습니다.
• 개발 및 유지보수의 용이성
  • API에서 하나의 방법만을 제공하면, 이 기능에 대한 문서를 작성하고 유지하기가 더 쉬워집니다.
  • 또한, 버그 발생 시 해당 기능에 집중하여 문제를 해결할 수 있으며, 기능을 개선하는 경우에도 변경해야 할 부분이 명확해집니다.

3. Is it consistent, does it follow the principle of least surprises?

• API가 전반적으로 일관된 디자인을 가지고 있으며, 사용자가 예상치 못한 동작을 경험하지 않도록 설계되었는지 확인
• "최소 놀람의 원칙"은 사용자가 이미 알고 있는 패턴과 유사하게 API가 동작함으로써 직관적으로 사용할 수 있게 하는 디자인 원칙
• 예를 들어, 파일을 "저장"하는 기능을 가진 버튼을 눌렀을 때, 사용자는 해당 파일이 실제로 저장되기를 기대합니다. 만약 그 버튼이 파일을 삭제한다면, 이는 최소 놀람의 원칙에 어긋나는 것입니다.

4. Clean split of API/internals, without internals leaking in the API?

• API 디자인이 내부 구현 세부 사항을 노출하지 않고, 명확하게 API와 내부 구현을 분리하고 있는지 평가
• 내부 구현이 API에 노출되면, 내부 구조의 변경이 API 변경으로 이어질 수 있어 사용자에게 부담을 주고 유지보수를 어렵게 함
• 여기서 "내부 구현 세부 사항"이란, API가 제공하는 기능을 실제로 어떻게 실행하는지에 대한 코드와 로직을 말합니다.
• 이러한 분리를 통해, API를 사용하는 외부 개발자나 사용자는 API의 기능만을 이해하고 사용할 수 있으며, 그 기능이 어떻게 구현되어 있는지는 신경 쓸 필요가 없습니다. 이는 몇 가지 중요한 장점을 가집니다:
• 1. 유지보수 용이성
• 2. 사용자 부담 감소

5. Are there no breaking changes to user-facing parts (API classes, configuration, metrics, log formats, etc.)?

• 새로운 API 변경이 기존 사용자에게 영향을 미치는 호환성 문제를 일으키지 않는지 확인
• 사용자에게 영향을 주는 파트의 변경은 기존 시스템의 동작에 영향을 줄 수 있으므로, 이를 철저히 검토해야 함

6. Is a new API generally useful and not overly specific?

• 새로 도입된 API가 너무 특정한 경우보다는 일반적으로 유용하도록 설계되었는지 평가
• API가 너무 특정한 경우에는 재사용성이 낮아지고, 다른 상황이나 프로젝트에서 활용하기 어려워질 수 있음

---

리뷰 대상 2: Implementation Semantics (구현 세부사항에 대한 검토)

• 코드 리뷰 시, 두번쨰로 중요한 부분

1. Does it satisfy the original requirements?

• 구현된 코드가 프로젝트나 기능의 초기 요구 사항을 충족하는지 검토
• 예를 들어, 온라인 쇼핑 앱에서 사용자가 상품을 장바구니에 추가할 수 있는 기능이 요구된 경우, 이 기능이 제대로 구현되었는지 확인

2. Is it logically correct?

• 코드가 논리적으로 올바른지, 즉 프로그래밍 로직이 정확한지 평가
• 예를 들어, 계산기 앱에서 두 수를 더하는 함수가 있을 때, 이 함수가 모든 입력에 대해 올바른 결과를 반환하는지 확인

3. Is there no unnecessary complexity?

• 코드가 필요 이상으로 복잡하지 않은지 검토
• 복잡한 코드는 버그 발생 가능성을 높이고 유지보수를 어렵게 만듭니다.
• 예를 들어, 간단한 문제를 해결하기 위해 과도한 수의 조건문과 루프를 사용했다면, 이는 불필요한 복잡성으로 간주될 수 있습니다.

4. Is it robust (no concurrency issues, proper error handling, etc.)?

• 코드가 견고한지, 즉 동시성 문제가 없고, 오류 처리가 적절하게 이루어졌는지 평가
• 예를 들어, 웹 서버에서 여러 사용자가 동시에 데이터를 업데이트할 경우 발생할 수 있는 데이터 불일치 문제를 적절히 처리하는지 확인

5. Is it performant?

• 코드가 성능 면에서 효율적인지 검토
• 데이터베이스 쿼리, 알고리즘 선택 등이 시스템의 응답 시간과 처리량에 미치는 영향을 평가
• 예를 들어, 대용량 데이터를 처리할 때 시간 복잡도가 낮은 알고리즘을 선택하는지 확인

6. Is it secure (e.g., no SQL injections, etc.)?

• 구현이 보안상 안전한지 확인
• 코드가 SQL 인젝션 공격과 같은 취약점을 방지하는지 등을 평가
• 예를 들어, 웹 애플리케이션에서 사용자 입력을 적절히 검증하고 이스케이핑하는지 확인

7. Is it observable (e.g., metrics, logging, tracing, etc.)?

• 코드가 관찰 가능한지, 즉 시스템의 상태를 모니터링하고 문제를 진단할 수 있는 적절한 메트릭스, 로깅, 추적 기능을 포함하고 있는지 검토
• 예를 들어, 서버 애플리케이션에서 처리된 요청의 수, 응답 시간 등을 로그로 기록하고 분석할 수 있는지 확인

8. Do newly added dependencies pull their weight? Is their license acceptable?

• 새로 추가된 의존성이 그 가치를 제공하는지, 그리고 그들의 라이센스가 프로젝트 요구사항과 호환되는지 평가
• 예를 들어, 새로운 라이브러리를 도입했을 때, 이 라이브러리가 추가적인 유용성을 제공하는지, 그리고 사용된 라이센스가 오픈소스 라이센스 조건과 맞는지 확인

---

리뷰 대상 3: Documentation

• 코드 리뷰 시, 세번쨰로 중요한 부분

1. New features reasonably documented?

• 새로운 기능이 적절하게 문서화되었는지 확인
• 새로운 기능에 대한 문서화는 사용자와 다른 개발자가 해당 기능을 이해하고 올바르게 사용할 수 있도록 하는 데 필수적
• 예를 들어, 새로운 API 메소드가 도입된 경우, 그 사용법, 예상되는 입력과 반환 값, 발생 가능한 예외 등이 문서에 명확하게 기술되어야 함

2. Are the relevant kinds of docs covered: README, API docs, user guide, reference docs, etc.?

• 필요한 모든 종류의 문서가 포함되어 있는지 검토합니다. 각 문서 유형은 다른 목적을 가지고 있습니다:
  • README: 프로젝트의 개요, 설치 방법, 빠른 시작 가이드 등을 제공
  • API 문서: 개발자가 API를 어떻게 사용할 수 있는지에 대한 상세 정보를 제공
  • 사용자 가이드: 비개발자 사용자를 위해 제품이나 서비스의 사용 방법을 설명
  • 참조 문서: 시스템이나 프로그램의 상세한 기술적 사항을 설명
• 예를 들어, API를 개발한 경우, API 문서가 완벽해야 하며, 사용자 가이드가 비개발자도 이해할 수 있도록 쓰여져야 함

3. Are docs understandable, are there no significant typos and grammar mistakes?

• 문서가 이해하기 쉽고, 중대한 오타나 문법 오류가 없는지 확인합니다.
• 문서의 명확성은 사용자가 정보를 정확히 이해하고 적용할 수 있게 하는 데 중요합니다.
• 문서의 오류는 사용자의 혼란을 야기하고, 잘못된 정보의 전달로 이어질 수 있습니다. 예를 들어, API 문서에서 함수 이름이 잘못 기술되어 있으면, 개발자가 해당 함수를 잘못 사용할 수 있습니다.