좋은 코드 리뷰는 취향 검사가 아니라 위험 확인입니다

프론트엔드 코드 리뷰에서 가장 흔한 실수는 변수명, 줄바꿈, 컴포넌트 분리 같은 취향 문제에 먼저 에너지를 쓰는 것입니다. 물론 읽기 쉬운 코드는 중요하지만, 운영 서비스에서 더 큰 비용을 만드는 것은 화면이 갱신되지 않거나, 입력값이 사라지거나, 모바일에서 버튼을 누를 수 없거나, 실패 응답을 사용자가 이해하지 못하는 문제입니다. 코드 리뷰는 이런 위험을 배포 전에 줄이는 절차여야 합니다.

Frontend Note의 코드 리뷰 기준은 동작, 데이터, 타입, 접근성, 성능, 에러 처리, 유지보수성 순서로 확인합니다. 이 순서는 작은 PR에서도 그대로 적용할 수 있고, 리뷰어가 여러 명일 때도 의견이 흩어지는 것을 막아줍니다.

1. 사용자 흐름이 끝까지 이어지는지 확인하기

가장 먼저 볼 것은 코드 모양이 아니라 사용자가 실제로 하려는 일이 끝나는지입니다. 검색어를 입력하면 결과가 바뀌는지, 저장 버튼을 누르면 저장 중 상태가 보이는지, 실패했을 때 다시 시도할 수 있는지 확인합니다. 특히 폼, 필터, 모달, 드롭다운은 정상 케이스만 보면 문제를 놓치기 쉽습니다.

  • 빈 데이터가 들어와도 화면이 깨지지 않는가?
  • 느린 네트워크에서 중복 제출이 막히는가?
  • 성공 후 사용자에게 다음 행동이 명확한가?
  • 뒤로 가기, 새로고침, 모바일 화면에서도 흐름이 유지되는가?

2. 타입은 통과하지만 런타임에서 틀릴 수 있는 부분 찾기

TypeScript를 사용해도 모든 오류가 사라지지는 않습니다. API 응답이 비어 있거나, 선택 필드가 누락되거나, 숫자로 기대한 값이 문자열로 들어오는 경우는 여전히 런타임에서 문제가 됩니다. 리뷰에서는 타입 선언이 실제 외부 데이터와 맞는지, 방어 로직이 필요한 위치가 어디인지 확인해야 합니다.

type User = {
  id: string;
  name?: string;
};

function UserName({ user }: { user: User }) {
  return <span>{user.name ?? "이름 없음"}</span>;
}

이 예시처럼 선택 값에는 화면에서 보여줄 기본 문구가 있어야 합니다. 단순히 타입 오류가 없다는 이유만으로 안정적인 코드는 아닙니다.

3. 접근성은 마지막 점검이 아니라 리뷰 기준입니다

버튼처럼 보이는 요소가 실제 button인지, 링크 텍스트가 목적지를 설명하는지, 폼 label이 input과 연결되어 있는지 확인합니다. 아이콘 버튼에는 aria-label이 필요하고, 모달은 열릴 때 포커스가 내부로 이동해야 합니다. 접근성은 별도의 고급 기능이 아니라 HTML을 의미에 맞게 쓰는 기본 규칙입니다.

4. 성능 리뷰는 추측보다 변경 범위를 봅니다

모든 PR에서 성능 측정을 길게 할 필요는 없습니다. 대신 목록 렌더링, 이미지 추가, 대형 라이브러리 도입, 전역 상태 변경처럼 성능 영향을 만들기 쉬운 변경은 표시해야 합니다. 리뷰어는 새 의존성이 초기 번들에 들어가는지, 이미지 크기가 적절한지, 불필요한 반복 계산이 생기지 않는지 확인합니다.

const visibleItems = useMemo(() => {
  return items.filter(item => item.label.includes(keyword));
}, [items, keyword]);

이런 최적화도 실제로 목록이 크고 계산 비용이 있을 때 의미가 있습니다. 리뷰에서는 최적화를 추가했는지보다 왜 필요한지 설명되어 있는지를 봐야 합니다.

5. 에러 메시지는 개발자가 아니라 사용자를 향해야 합니다

API 요청이 실패했을 때 콘솔에만 오류를 남기면 사용자는 아무것도 할 수 없습니다. 실패 원인이 권한, 네트워크, 입력 오류, 서버 오류 중 무엇인지에 따라 안내가 달라져야 합니다. 리뷰에서는 사용자가 다시 시도할 수 있는지, 입력값이 보존되는지, 오류 메시지가 화면 가까이에 표시되는지 확인합니다.

실무 코드 리뷰 순서

  1. PR 설명에서 변경 목적과 확인 방법을 먼저 읽습니다.
  2. 사용자 흐름을 기준으로 정상, 빈 데이터, 실패 케이스를 확인합니다.
  3. 타입과 API 응답의 경계에서 방어 로직이 필요한지 봅니다.
  4. button, a, label, heading 같은 기본 HTML 의미를 확인합니다.
  5. 번들, 이미지, 목록 렌더링, 전역 상태 변경의 영향을 확인합니다.
  6. 테스트나 수동 확인 기록이 변경 위험에 맞는지 봅니다.

Frontend Note 실무 노트

코드 리뷰는 모든 문제를 완벽히 찾는 자리가 아닙니다. 대신 배포 후 큰 비용이 될 문제를 먼저 줄이는 합의된 절차입니다. 리뷰 코멘트는 “이 방식이 마음에 들지 않는다”보다 “이 입력이 비어 있으면 사용자가 다음 단계로 갈 수 없다”처럼 위험과 사용자 영향을 함께 적는 편이 좋습니다.

팀에서 리뷰 품질을 올리고 싶다면 체크리스트를 PR 템플릿에 넣는 것도 좋은 방법입니다. 구현자는 스스로 확인한 항목을 표시하고, 리뷰어는 빠진 위험을 중심으로 확인할 수 있습니다.

참고 자료와 업데이트 기준

코드 리뷰 기준은 팀의 기술 스택과 서비스 성격에 따라 달라질 수 있습니다. 이 글은 React와 TypeScript 기반의 일반적인 프론트엔드 서비스에 맞춘 기준이며, 공식 문서와 도구 변화가 있으면 내용을 다시 점검합니다.