HTML 구조를 보기 좋게 정리하는 Before & After: 초보 코드 리뷰 가이드
1. 주제 소개
HTML은 화면을 "보이게" 만드는 언어이지만, 실무에서는 "읽히게" 만드는 능력이 더 중요합니다. 초보 단계에서 자주 나오는 문제는 div를 계속 중첩해 구조가 깊어지고, 클래스 이름이 뒤섞이며, 영역 구분이 없어 수정할 때 길을 잃는 상황입니다. 화면은 정상 출력되는데 코드만 보면 어디가 헤더인지, 어디가 본문인지, 어떤 블록이 반복되는 카드인지 한눈에 파악하기 어려운 상태가 됩니다. 이 경우 디자인 변경이나 기능 추가 시 작은 수정도 큰 스트레스로 이어집니다.
이번 글은 HTML 구조를 보기 좋게 정리하는 기본 기준을 Before & After 관점으로 설명합니다. 핵심은 복잡한 기술이 아니라 구조적 습관입니다. 의미 단위로 구획하고, 같은 패턴은 같은 형태로 작성하며, 들여쓰기와 네이밍 규칙을 일관되게 유지하는 것만으로도 코드 품질이 크게 달라집니다. 결과적으로 협업 시 커뮤니케이션 비용이 줄고 유지보수 속도가 빨라집니다.
2. 핵심 내용
첫 번째 기준은 시맨틱 태그 우선입니다. 모든 구획을 div로 처리하면 기능은 동작해도 문서 의미가 사라집니다. `header`, `main`, `section`, `article`, `aside`, `footer` 같은 태그를 사용하면 코드만 읽어도 레이아웃 의도가 보입니다. 접근성 도구나 검색 엔진도 구조를 더 잘 이해할 수 있어 부가 효과가 큽니다. 두 번째 기준은 깊이 제한입니다. 중첩이 깊어질수록 추적 비용이 급격히 증가하므로, 가능하면 3~5단계 안에서 구조를 끝내는 것을 목표로 잡는 편이 좋습니다.
세 번째는 반복 패턴 통일입니다. 카드 목록, 댓글 행, 메뉴 아이템처럼 반복되는 블록은 마크업 순서를 고정해야 합니다. 예를 들어 카드가 항상 "썸네일, 제목, 설명, 버튼" 순서를 유지하면 CSS와 JS 선택자도 단순해집니다. 네 번째는 클래스 네이밍 일관성입니다. `box1`, `content2`, `item-new`처럼 즉흥적으로 지으면 유지보수 시 의미가 흐려집니다. 반면 `post-card`, `post-card__title`, `post-card__meta`처럼 역할 중심으로 정리하면 파일이 길어져도 읽기 쉽습니다.
마지막으로 공백과 줄바꿈도 품질 요소입니다. 들여쓰기가 제각각이면 구조 인지가 무너집니다. 팀 규칙에 맞춰 탭 또는 스페이스를 통일하고, 속성이 많은 태그는 한 줄 기준을 정해 일관되게 배치하세요. 이런 기본 정리만으로도 코드 리뷰에서 지적되는 잡음이 크게 줄어듭니다.
3. 적용 방법
실전 적용은 어렵지 않습니다. 먼저 페이지를 영역 단위로 나눠 스케치를 합니다. 예를 들면 헤더, 필터 영역, 리스트, 페이지네이션, 푸터처럼 큰 블록부터 정의합니다. 다음으로 각 블록 안에서 반복 단위를 찾고, 같은 마크업 순서를 강제합니다. 그다음 불필요한 래퍼 div를 제거하고 시맨틱 태그로 교체합니다. 마지막으로 클래스명을 역할 기준으로 재정리하고, 들여쓰기와 줄바꿈을 포맷팅 규칙에 맞춰 통일합니다.
| 점검 항목 | Before | After |
|---|---|---|
| 문서 의미 | div 중심으로만 구성 | header/main/section/article 등 시맨틱 구조 적용 |
| 중첩 깊이 | 불필요한 래퍼가 많아 추적 어려움 | 필요한 컨테이너만 유지해 깊이 단순화 |
| 반복 블록 | 항목마다 태그 순서가 조금씩 다름 | 반복 단위의 마크업 순서 통일 |
| 네이밍 | box, item1, content-new 등 임시 이름 | 역할 중심 클래스명으로 의도 명확화 |
Before 코드에서는 화면 일부를 수정하려고 할 때 관련 태그를 찾는 데 시간이 오래 걸립니다. After 코드에서는 블록 이름과 구조가 일치하므로 위치 파악이 빠르고, CSS 적용 범위도 예측하기 쉽습니다. 특히 팀 작업에서 "어디를 건드려야 하는지" 설명하는 시간이 줄어들어 생산성이 올라갑니다. HTML 정리는 디자인 작업 이전에 개발 효율을 확보하는 기반 작업이라고 보면 됩니다.
4. 정리
보기 좋은 HTML 구조는 취향 문제가 아니라 유지보수 전략입니다. 시맨틱 태그 사용, 중첩 최소화, 반복 패턴 통일, 네이밍 일관성이라는 네 가지 기준만 지켜도 코드의 읽기 난이도가 크게 낮아집니다. 초보 단계에서는 눈에 보이는 결과물에만 집중하기 쉽지만, 장기적으로는 코드 구조가 개발 속도를 결정합니다. 오늘 작성하는 작은 마크업 한 줄이 다음 주의 수정 시간을 줄여 준다는 관점으로 접근해 보세요. 결국 좋은 HTML은 브라우저뿐 아니라 사람에게도 친절한 문서입니다.
5. 자주 묻는 질문
Q1. div만 써도 동작하는데 시맨틱 태그를 꼭 써야 하나요?
필수는 아니지만 권장됩니다. 시맨틱 태그를 쓰면 구조 이해가 쉬워지고 접근성, 유지보수, 협업 측면에서 분명한 이점이 있습니다.
Q2. 클래스명 규칙은 어떤 걸 쓰는 게 좋나요?
팀에서 이미 쓰는 규칙이 있으면 그걸 따르는 것이 우선입니다. 없다면 역할 중심 네이밍과 일관된 접두 패턴을 정해 문서화하는 것부터 시작하세요.
Q3. 기존 페이지가 너무 복잡한데 어디부터 정리해야 할까요?
변경이 자주 일어나는 화면부터 시작하세요. 큰 구조를 먼저 정리하고, 반복 블록을 통일한 뒤 네이밍을 정리하면 효율적으로 개선할 수 있습니다.