좋은 주석이란 무엇일까?
프로젝트를 진행하다 보면 한 번쯤 이런 생각을 하게 됩니다.
"나중에 유지보수할 때를 대비해서, 주석을 꼼꼼하게 달아두자."
그래서 코드 한 줄 한 줄마다 설명을 붙이기 시작합니다. 그런데 어느 날 다시 코드를 열어보면, 주석이 오히려 코드를 읽는 흐름을 끊고 있다는 걸 깨닫게 됩니다. 설명이 많은데 오히려 이해하기가 더 어렵고, 마치 AI가 자동으로 생성한 것처럼 부자연스럽게 느껴지기도 합니다.
그렇다면 주석은 많을수록 좋은 걸까요?
결론부터 말하면 그렇지 않습니다. 좋은 주석은 양이 아니라 위치와 내용이 결정합니다. 코드가 스스로 말할 수 있는 부분까지 주석으로 덮어버리면, 오히려 읽어야 할 텍스트만 늘어날 뿐입니다.
그래서 이 글에서는 좋은 주석과 나쁜 주석의 차이, 그리고 실무에서 실제로 쓰이는 주석 스타일까지 정리해보려 합니다.
좋은 주석이란?
좋은 주석의 핵심은 하나입니다. "무엇"이 아니라 "왜"를 설명한다.
코드는 무엇을 하는지 스스로 말할 수 있어야 합니다. 주석은 코드만으로는 알 수 없는 의도, 맥락, 배경을 전달할 때 비로소 가치가 생깁니다.
# 좋지 않은 주석 — 코드를 그대로 번역
i = i + 1 # i에 1을 더한다
# 좋은 주석 — 이유를 설명
i = i + 1 # 인덱스는 0-based이므로 실제 순번 표시를 위해 1 보정두 줄의 코드는 동일하지만 주석의 질은 완전히 다릅니다. 첫 번째는 코드를 읽을 수 있는 사람이라면 누구나 아는 내용이고, 두 번째는 코드만 봐서는 알 수 없는 이유를 담고 있습니다.
좋은 주석은 대체로 이런 상황에서 등장합니다.
- 의도 주석 — 왜 이 방식을 선택했는지 다른 방법을 쓰지 않은 이유
- 경고 주석 — 이 코드를 건드리면 생길 수 있는 부작용
- 복잡한 로직 설명 — 비즈니스 규칙이나 수식의 출처와 맥락
- TODO / FIXME — 의도적으로 남긴 미완성과 그 이유
나쁜 주석은 어떤 형태일까?
나쁜 주석은 단순히 "없는 것보다 못한" 수준에 그치지 않습니다. 잘못된 주석은 코드를 읽는 사람을 오히려 혼란스럽게 만들고, 유지보수를 더 어렵게 만듭니다.
1. 코드를 그대로 번역한 주석
# 리스트를 순회한다
for item in items:
pass코드를 읽을 수 있는 사람이라면 이미 아는 내용입니다. 노이즈만 추가될 뿐입니다.
2. 오래되어 코드와 어긋난 주석
# 사용자 이름을 반환한다
def get_user_email():
...함수는 바뀌었지만 주석은 그대로입니다. 이런 주석은 없는 것보다 훨씬 위험합니다. 다음 사람이 주석을 믿고 잘못된 방향으로 이해할 수 있기 때문입니다.
3. 주석 처리된 코드
# old_function()
# legacy_process(data)"나중에 쓸 수도 있어서"라는 이유로 남겨두는 경우가 많지만, 그 역할은 Git이 대신합니다. 주석 처리된 코드는 맥락 없이 쌓이면 코드베이스를 읽기 어렵게 만듭니다.
4. 감정이나 넋두리가 담긴 주석
# 왜 이렇게 짰는지 모르겠음
# 건드리면 터짐 ㅠ작성하는 순간엔 속이 시원할 수 있지만, 맥락 없는 불안감만 남깁니다.
차라리 왜 위험한지를 설명하는 편이 훨씬 낫습니다.
실무에서 쓰이는 주석 스타일
JSDoc / Docstring — 공개 API와 함수에는 필수
팀원이 함수를 사용할 때 코드 내부를 열어보지 않아도 되도록 입력과 출력, 예외 상황을 명시합니다.
/**
* 사용자 인증 토큰을 검증합니다.
* 만료된 토큰은 자동으로 재발급을 시도합니다.
*
* @param {string} token - Bearer 토큰
* @returns {Promise} 인증된 사용자 객체
* @throws {AuthError} 토큰이 유효하지 않을 경우
*/
async function verifyToken(token) { ... }인라인 주석 — 복잡한 조건이나 규칙에만
# 비밀번호 정책: 대소문자 + 숫자 + 특수문자 각 1개 이상 (보안팀 정책 v2.3)
PASSWORD_REGEX = r'^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])'정규식처럼 코드 자체로는 의도를 파악하기 어려운 경우, 왜 이 규칙인지를 한 줄로 남겨두면 나중에 수정할 때 큰 도움이 됩니다.
TODO / FIXME / HACK — 팀 내 컨벤션으로 통일
// TODO(홍길동): 캐싱 레이어 추가 필요 — 현재 매 요청마다 DB 조회 발생
// FIXME: 입력값이 null일 때 크래시 발생 가능, 예외 처리 필요
// HACK: 라이브러리 버그 우회 — v3.2 업그레이드 후 제거 예정
단순히 TODO만 남기는 것보다 누가 / 왜 / 언제까지를 함께 적으면 나중에 정리하기 훨씬 수월합니다.
마치며
주석을 쓰기 전에 스스로에게 한 번 물어보는 습관이 도움이 됩니다.
이 주석이 없으면 다음 사람이 이 코드를 이해하기 어려울까?
코드 자체를 더 명확하게 고쳐서 주석 없이도 읽힐 수 있을까?
"무엇"이 아니라 "왜"를 설명하고 있나?
주석은 코드가 말하지 못하는 이야기를 담는 곳입니다. 많이 달수록 좋은 게 아니라, 꼭 필요한 곳에 정확하게 있을 때 비로소 가치가 생깁니다. 다음 사람이 코드를 읽으며 고마워할 주석, 그게 좋은 주석의 기준이 아닐까요?
