한 달 전에 내가 만든 HTML 파일을 다시 열었을 때 무슨 생각으로 이걸 짰는지 도무지 기억이 안 났다. div가 왜 이렇게 중첩되어 있는지, 이 클래스 이름은 왜 이렇게 지었는지. 내가 짠 코드인데 남이 짠 것처럼 낯설었다. 그날 이후로 주석을 제대로 달기 시작했다.
티스토리 스킨을 수정하다가 한 달 전에 짰던 코드를 다시 열어본 적 있으신가요. 저는 그 순간 "이 div는 왜 여기 있지?"를 속으로 수십 번 되뇌었습니다. HTML 주석(comment)은 브라우저가 읽지 않는 메모 공간인데, 이걸 제대로 쓰면 코드 관리 방식 자체가 달라집니다. 직접 겪고 나서야 그 차이를 실감했습니다.
주석 없이 짠 코드가 한 달 뒤 낯선 이유
처음 티스토리 스킨을 손댈 때 저는 주석을 전혀 달지 않았습니다. 제가 직접 짠 코드니까 당연히 기억할 수 있을 거라고 생각했습니다. 그런데 한 달 뒤 같은 파일을 열었더니 div 태그가 왜 그렇게 중첩되어 있는지, 특정 클래스(class)가 왜 그 이름인지 전혀 떠오르지 않았습니다. 여기서 클래스란 HTML 요소에 스타일을 적용하기 위해 붙이는 식별자로, 프로젝트가 커질수록 이름의 의도를 기억하기가 어려워집니다. 구조를 다시 파악하는 데만 한 시간 가까이 걸렸고, 솔직히 이건 예상 밖이었습니다.
HTML 주석은 <!-- 내용 --> 형태로 작성합니다. 브라우저는 이 영역을 렌더링(rendering)하지 않습니다. 렌더링이란 브라우저가 HTML 코드를 읽어 화면에 시각적으로 표시하는 과정을 말합니다. 구글 검색 로봇 역시 주석 안의 내용을 색인(indexing)하지 않으므로, 아무리 많은 메모를 남겨도 실제 페이지 출력이나 SEO에 영향을 주지 않습니다. 여기서 색인이란 검색 엔진이 웹페이지의 내용을 수집하고 분류해 검색 결과에 반영할 수 있도록 저장하는 작업을 의미합니다.
주석을 제대로 활용하려면 목적을 나눠서 생각하는 것이 좋습니다. 제가 직접 써보면서 실제로 도움이 됐던 용도를 정리하면 다음과 같습니다.
- 헤더, 푸터, 사이드바 등 큰 구역의 시작과 끝에 구역 표시 주석을 달아 코드 전체의 지도를 만든다
- 삭제 대신 주석 처리(commenting out)로 코드를 임시 비활성화해 언제든 되살릴 수 있게 한다
- 수정 날짜와 이유를 함께 기록해 나중에 맥락을 바로 파악할 수 있게 한다
<!-- TODO: 반응형 처리 필요 -->형태로 할 일 목록을 코드 안에 직접 관리한다
W3C(World Wide Web Consortium)는 HTML 표준 명세에서 주석을 코드 가독성과 유지보수를 위한 공식 문법으로 규정하고 있습니다(출처: W3C HTML 명세). 처음에는 이런 규칙이 형식적으로 느껴질 수 있지만, 실제 작업량이 늘어나면서 그 이유를 몸으로 이해하게 됩니다.
주석 습관이 코드 이해도를 올리는 이유
코드를 삭제하려다가 혹시 나중에 필요할까 봐 망설인 경험, 한 번쯤 있으실 겁니다. 저는 그런 상황에서 주석 처리를 써봤더니 실수에 대한 부담이 확연히 줄었습니다. 코드 한 줄을 지우는 대신 <!--와 -->로 감싸두면 기능은 꺼지지만 코드는 그대로 남습니다. 브라우저는 읽지 않으니 화면에는 반영되지 않고, 필요할 때 주석만 해제하면 즉시 복구됩니다. 제 경험상 이 방법이 없었다면 스킨 수정 작업에서 돌이킬 수 없는 실수를 훨씬 많이 했을 것 같습니다.
더 중요한 건 주석을 쓰는 행위 자체가 코드 이해도를 높인다는 점입니다. 설명을 글로 옮기려면 먼저 내가 그 코드가 하는 일을 명확히 알아야 합니다. 주석을 달지 못하겠다면 그 코드를 아직 제대로 파악하지 못한 신호입니다. 실제로 DOM(Document Object Model) 구조가 복잡해질수록 이 차이가 더 분명하게 드러납니다. DOM이란 브라우저가 HTML을 읽어 각 요소를 트리 구조로 표현한 것으로, 자바스크립트나 CSS로 특정 요소를 선택하거나 변경할 때 기준이 되는 구조입니다.
스킨 파일이 500줄을 넘어가기 시작했을 때 저는 주석 없이는 작업 자체가 불가능하겠다는 걸 처음 실감했습니다. 구역 표시 주석이 없으면 헤더와 본문 영역의 경계가 어디인지 스크롤을 위아래로 반복해서 찾아야 했고, 수정 이력이 없으면 같은 부분을 두 번 손대는 일도 생겼습니다. MDN Web Docs는 HTML 주석을 코드 유지보수성(maintainability)을 확보하는 기본 수단으로 소개하고 있는데, 실무에서 직접 겪어보면 그 설명이 과장이 아니라는 걸 알게 됩니다(출처: MDN Web Docs).
블로그 운영 강의에서 HTML 주석을 제대로 다루는 경우가 드문 것도 아쉽습니다. 그냥 "이렇게 생긴 것"이라고만 소개하고 넘어가는 경우가 대부분인데, 제 경험상 스킨을 오래 관리하면 관리할수록 주석의 무게가 달라집니다. 처음 스킨에 손댈 때부터 구역 표시와 수정 이력 메모를 습관으로 잡아두는 것이 가장 효율적입니다.
주석이 단순한 메모 수단이라고 생각했다면, 실제로 한 번 500줄짜리 주석 없는 파일과 구역 주석이 잘 달린 파일을 나란히 열어보시기 바랍니다. 그 차이가 코딩 실력의 차이보다 작업 속도에 더 큰 영향을 줍니다. 당장 오늘 수정하는 코드부터 구역 시작과 끝에 한 줄씩 메모를 남겨두는 것만으로도 한 달 뒤의 본인이 고마워할 것입니다.