코드 리뷰에서 공백과 줄바꿈 이야기만 길어지면 정작 봐야 할 로직을 놓치기 쉽습니다. 그렇다고 “각자 편한 대로” 두면 작은 수정에도 파일 전체가 달라져 보입니다. 스타일 가이드를 만드는 이유는 어느 취향이 우월한지 결정하기보다 이런 마찰을 줄이기 위해서라고 생각합니다.
처음부터 수십 페이지를 만들 필요는 없습니다. 저장했을 때 파일이 어떻게 바뀌는지부터 맞추는 편이 효과를 확인하기 쉽습니다.
공백 규칙은 저장소에 남긴다
다음은 C# 프로젝트에서 출발점으로 쓸 수 있는 .editorconfig 예제입니다. 실제 프로젝트가 탭이나 CRLF를 사용한다면 기존 규칙에 맞춰 조정합니다.
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
[*.cs]
indent_style = space
indent_size = 4
[*.md]
trim_trailing_whitespace = false
Markdown의 행 끝 공백은 줄바꿈 의미를 가질 수 있어 예외로 두었습니다. 프로젝트에 따라 Makefile의 탭처럼 파일 형식 자체가 요구하는 문법도 있으므로, 전역 규칙을 무작정 넓히지 않습니다.
EditorConfig는 지원하는 에디터가 읽는 설정입니다. 파일을 추가했다고 모든 코드가 자동 정리되거나 CI가 실패하도록 바뀌지는 않습니다. 사용하는 포매터가 어떤 설정을 지원하는지도 별도로 확인해야 합니다.
기존 코드에는 작게 도입한다
진행 중인 프로젝트라면 작업 브랜치가 많이 갈라진 시점에 전체 포매팅부터 하는 것은 피하고 싶습니다. 충돌이 늘어나고 기능 변경을 리뷰하기 어려워집니다. 먼저 새 파일이나 수정한 파일에 적용할지, 일정 시간을 정해 전체를 맞출지 팀의 작업 상태에 따라 고릅니다.
전체를 바꾼다면 포맷만 적용한 변경을 따로 남깁니다. 그 변경에 변수 이름 수정이나 null 처리까지 섞지 않습니다. 그래야 나중에 장애를 추적할 때 기계적인 변경을 구분하기 쉽습니다. git diff --check는 공백 오류를 찾는 데 도움이 되지만 프로젝트의 모든 스타일 규칙을 검증하는 포매터는 아닙니다.
CI에는 실제 저장 시 사용하는 도구와 같은 버전을 둡니다. 로컬과 CI의 포매터 버전이 다르면 개발자가 저장할 때마다 다시 실패할 수 있습니다. 생성 코드와 외부 패키지 등 직접 관리하지 않는 파일의 제외 범위도 함께 정합니다.
문서에는 도구가 모르는 판단을 적는다
공백 규칙을 문서에 길게 반복하는 대신 프로젝트의 용어와 경계를 남기는 편이 좋습니다. 예를 들면 ‘아이템의 고유 식별자는 ItemId로 부른다’, ‘UI에서 저장 파일에 직접 접근하지 않는다’, ‘이벤트 구독 해제는 소유 컴포넌트가 책임진다’처럼 코드 리뷰에 쓸 수 있는 내용입니다.
좋은 예제와 나쁜 예제를 하나씩 붙이면 추상적인 문장보다 이해하기 쉽습니다. 단, 그 기준이 지금 코드와 다르다면 새 규칙을 기존 코드 전체에 즉시 요구할지, 변경하는 부분부터 맞출지 정해야 합니다. 적용 범위가 없으면 규칙을 지키려고 관련 없는 파일까지 고치게 됩니다.
도입한 뒤에는 리뷰가 달라졌는지 본다
설정 파일 개수가 늘었다고 성공한 것은 아닙니다. 작은 기능 수정에서 포맷 변경이 사라졌는지, 새 팀원이 같은 결과를 얻을 수 있는지, 스타일 때문에 다시 요청하는 리뷰가 줄었는지를 봅니다.
규칙도 수정할 수 있어야 합니다. 특정 이름 규칙이 실제로 코드 검색을 어렵게 만들거나 자동 생성 코드와 충돌하면 이유를 남기고 바꿉니다. 중요한 것은 강한 표현으로 규칙을 지키게 하는 일이 아니라, 같은 코드를 읽을 때 쓸데없는 해석이 줄어드는 것입니다.