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