diff를 읽기 쉽게 만드는 화면 구성 원칙

diff를 읽기 쉽게 만드는 화면 구성 원칙

diff 화면의 목적은 코드를 예쁘게 보여주는 것이 아닙니다. 변경의 의도와 위험을 빠르게 판단하게 만드는 것입니다. 좋은 diff 뷰어는 사용자가 세 가지 질문에 빨리 답하도록 도와야 합니다. 무엇이 바뀌었는가, 왜 위험한가, 다음으로 어디를 봐야 하는가.

파일보다 변경 단위가 먼저다

리뷰어는 파일 전체를 읽지 않습니다. 변경된 덩어리를 훑고, 그 덩어리가 기존 흐름에 어떤 영향을 주는지 확인합니다. 따라서 화면 상단에는 파일명만 둘 것이 아니라 추가, 삭제, 수정 비율과 변경 블록 수가 보여야 합니다. 긴 파일에서는 다음 변경 지점으로 이동하는 조작이 필수입니다.

라인 번호도 장식이 아닙니다. 댓글, 버그 리포트, 배포 후 추적에서 같은 위치를 공유하기 위한 좌표입니다. 라인 번호가 흐려지거나 복사하기 어렵다면 리뷰 도구로서의 신뢰도가 떨어집니다.

공백은 숨기되 무시하지 않는다

공백 변경은 리뷰 피로도를 크게 만듭니다. 기본 화면에서는 의미 있는 변경을 우선 보여주되, 필요하면 공백 변경을 켤 수 있어야 합니다. 중요한 것은 숨김과 삭제를 혼동하지 않는 것입니다. 공백을 접더라도 실제 패치에는 존재한다는 사실을 표시해야 합니다.

색도 같은 원칙입니다. 빨강과 초록은 변경 방향을 알려줄 뿐, 변경의 중요도를 알려주지 않습니다. 삭제된 인증 조건 한 줄과 문장 수정 열 줄은 같은 색으로 보이지만 위험도는 다릅니다. 그래서 변경 블록의 맥락, 함수명, 주변 라인이 함께 필요합니다.

리뷰 속도는 탐색 구조에서 나온다

좋은 diff 화면은 사용자가 마우스 휠만 굴리게 만들지 않습니다. 파일 목록, 변경 블록 목록, 검색, 다음 변경 이동이 있어야 합니다. 리뷰가 길어질수록 탐색 구조가 품질을 결정합니다.

diff 뷰어를 설계할 때 저는 먼저 색을 정하지 않습니다. 리뷰어가 어떤 순서로 위험을 줄여 나갈지부터 그립니다. 화면 구성은 그 순서를 방해하지 않는 방식으로 따라와야 합니다.

Split과 Unified는 서로 다른 상황에 맞습니다.

Split View는 왼쪽과 오른쪽을 나란히 비교할 수 있어 변경 전후의 위치를 확인하기 좋습니다. 함수 이름, 문단 흐름, 설정 키처럼 줄 위치가 중요한 경우에 특히 유용합니다. 반면 Unified View는 변경만 이어서 볼 수 있어 화면 폭이 좁거나 모바일에서 읽기 편합니다.

한 가지 보기 방식만 제공하면 사용자의 문맥을 제한하게 됩니다. 코드 리뷰에서는 Split이 편한 순간이 있고, 문서 수정안에서는 Unified가 더 빠른 순간이 있습니다. Diff Viewer에서 두 모드를 전환할 수 있게 하는 이유도 이 때문입니다. 도구는 사용자의 현재 작업 방식에 맞춰 화면 밀도를 바꿀 수 있어야 합니다.

긴 변경 구간에서는 길을 잃지 않게 해야 합니다.

작은 변경은 줄 색상만으로 충분하지만, 수백 줄의 변경에서는 현재 위치를 놓치기 쉽습니다. 이때 필요한 것은 더 화려한 장식이 아니라 기준점입니다. 줄 번호, 변경 블록 간격, 섹션 제목, 이전/다음 변경 이동 같은 요소가 사용자의 방향 감각을 유지해 줍니다.

특히 리뷰어는 모든 변경을 같은 깊이로 읽지 않습니다. 먼저 큰 구조를 훑고, 위험한 구간을 찾고, 필요한 줄만 자세히 봅니다. diff 도구가 이 스캔 과정을 지원하면 검토 시간이 줄어듭니다. 반대로 모든 줄을 같은 강도로 보여주면 실제로 중요한 변경이 묻힐 수 있습니다.

붙여넣기 도구도 결과를 설명해야 합니다.

간단한 웹 diff 도구는 사용자가 두 텍스트를 붙여 넣고 결과를 확인하는 구조가 많습니다. 이때 “변경 없음”, “왼쪽만 있음”, “오른쪽만 있음” 같은 빈 상태 안내가 중요합니다. 결과가 비어 있을 때 그것이 정상인지, 입력이 잘못된 것인지 알 수 있어야 하기 때문입니다.

Diff Viewer는 복잡한 협업 플랫폼을 대체하려는 도구가 아닙니다. 짧은 코드 조각, 문서 수정안, 설정 파일 변경을 빠르게 비교하는 데 초점을 둡니다. 이 목적에서는 빠른 입력, 명확한 강조, 보기 전환, 공백 옵션이 핵심입니다. 작은 도구일수록 “무엇을 하지 않을지”가 분명해야 사용자가 기대를 정확히 맞출 수 있습니다.

실제 적용 메모

diff 화면을 만들 때 가장 먼저 정한 것은 색이 아니라 읽는 순서였습니다. 리뷰어가 보통 확인하는 순서는 다음과 같습니다.

1. 어떤 파일이 바뀌었는가
2. 변경량이 많은 파일은 무엇인가
3. 삭제된 조건문이나 권한 체크가 있는가
4. 공백 변경 때문에 실제 변경이 가려지는가

그래서 diff 도구에서는 코드 줄만 보여주면 부족합니다. 파일 목록, 변경 수, 다음 변경 위치 이동이 같이 있어야 합니다.

예를 들어 아래 두 변경은 같은 한 줄 변경처럼 보여도 위험도가 다릅니다.

- if (isAdmin) deleteComment(id)
+ deleteComment(id)

- margin: 12px;
+ margin: 14px;

리뷰 화면은 이 차이를 사용자가 빨리 발견하게 만들어야 합니다. 색상은 보조 수단이고, 실제 품질은 탐색 구조에서 나옵니다.