주석, 어디까지 써야 하고 어떻게 써야 할까? – 실무 주석 작성 기준

프로젝트를 하다 보면 자주 듣게 되는 말 중 하나가 "주석 좀 정리해 주세요"입니다. 주석은 코드의 이해를 돕기 위한 중요한 도구이지만, 과하거나 부정확하면 오히려 혼란만 가중시킵니다. 이 글에서는 실무에서 주석을 작성할 때 기준 삼을 수 있는 원칙과 예시를 정리합니다.

1. 왜 주석이 필요한가?

코드는 기본적으로 읽히기 위해 존재합니다. 주석은 다음과 같은 상황에서 특히 유용합니다.

• 복잡한 알고리즘이나 로직을 설명할 때
• 코드만 봐선 의도가 분명하지 않은 부분을 명시할 때
• 임시 처리, 예외 처리, 버그 회피 등 특수한 상황을 설명할 때
• 외부 API 호출이나 비즈니스 로직에 대한 맥락을 설명할 때

2. 실무에서 주석 작성의 기준

아래는 주석을 작성할 때 실무에서 자주 활용되는 기준입니다.

• 코드의 '무엇'보다 '왜'를 설명하라
  이미 코드로 드러나는 내용을 주석으로 반복하지 말고, 왜 그렇게 작성했는지를 설명합니다.

• 변경 가능성이 있는 부분은 주석을 줄인다
  주석은 코드보다 쉽게 오래 남습니다. 이후 코드가 바뀌었는데 주석이 갱신되지 않으면 오히려 혼란을 줍니다.

• 함수/메서드 단위에는 문서화 주석을 작성하되, 지나친 설명은 피한다
  함수의 목적, 입력값, 출력값 정도를 간단히 정리합니다.

• 불필요한 TODO/임시 코드 주석은 배포 전 반드시 제거
  ‘TODO’, ‘FIXME’, ‘HACK’ 같은 주석은 개발 중엔 유용하지만, 배포 시점에서는 기술부채가 됩니다.

• 업무 도메인 중심의 설명을 남긴다
  기술적인 설명보다 "이 요청은 고객 등급 기준을 조회함" 같은 업무 맥락 위주의 설명이 더 중요할 때가 많습니다.

3. 좋은 주석의 예시

# 사용자 등급별 할인율 적용 (등급 기준은 2024년 정책 기준)
def calculate_discount(user_grade):
    if user_grade == "VIP":
        return 0.2  # VIP는 20% 할인
    elif user_grade == "Regular":
        return 0.1  # 일반 회원은 10% 할인
    return 0

4. 나쁜 주석의 예시

# if 문으로 조건 확인
if user_grade == "VIP":  # VIP인지 확인
    return 0.2  # 0.2 리턴

이런 주석은 코드 자체가 말해주는 내용을 다시 반복하고 있어 불필요합니다.

5. 주석보다 더 좋은 건 '코드로 의도를 표현하는 것'

주석도 중요하지만, 가장 좋은 코드는 주석 없이도 의도가 드러나는 코드입니다. 예를 들어 변수명, 함수명만 명확하게 지어도 주석 없이 충분히 전달될 수 있습니다.

def get_discount_rate_by_membership(grade):
    ...

마무리

주석은 협업의 기본입니다. 하지만 무분별한 주석은 되레 코드 품질을 해칩니다. 주석은 '도움이 되는 설명'을 '최소한'으로 작성하는 것이 핵심입니다. 실무에서 주석은 팀을 위한 작은 배려이자, 스스로를 위한 기록입니다.

#코딩실무노트 #주석작성 #클린코드 #개발자팁 #협업팁