[주석 해석] 코드 한 줄의 진짜 의도를 읽는 법

검토 코멘트를 반영하여 새로운 글을 작성하겠습니다. 제공된 개요를 바탕으로 사실 오류, 논리 비약, 누락된 개념을 보완한 버전입니다.

---

주석과 문서에서 코드의 숨겨진 의도를 읽기

코드를 읽다 보면 “왜 이런 방식으로 구현했을까?”라는 의문이 든다. 주석과 문서는 그 답을 담고 있지만, 제대로 읽는 법을 모르면 무용지물이다. 개발자는 단순 설명이 아닌 제약 조건, 트레이드오프, 그리고 미래에 대한 경고를 읽어내야 한다.

주석의 여러 얼굴 이해하기

모든 주석이 같지 않다. 각 주석 유형은 서로 다른 의도를 담고 있다.
헤더 주석과 함수 내부 주석의 역할 구분
함수 최상단의 헤더 주석은 “이 함수가 뭐 하는 건가”를 설명하지만, 함수 내부 주석은 보통 “이 부분이 왜 필요한가”를 담는다. 예를 들어:

def calculate_discount(price, user_type):
    # 신규 사용자는 첫 구매 할인 미적용 (법적 이유: 프로모션 약관 참고)
    if user_type == "new":
        return price
    
    # 기존 사용자 할인율: VIP 20%, 일반 10%
    return price * (0.8 if user_type == "vip" else 0.9)

헤더 주석은 함수의 계약(contract)을 설명하고, 내부 주석은 그 계약을 왜 이렇게 맺었는지 설명한다.
간과되는 주석들

• 라이선스 주석: 파일 상단의 저작권이나 라이선스 선언 — 코드 재사용, 변경, 배포 시 법적 제약을 나타낸다.
• TODO/FIXME 주석: 미완료 또는 알려진 버그 — “언제 누가 해야 하는가”가 기록되면 더 유용하다.
• JSDoc / docstring: 타입, 파라미터, 반환값, 예외를 형식화한 주석 — IDE 자동완성과 문서 자동 생성을 가능하게 한다.

자기 문서화 코드와 주석의 긴장 관계

좋은 코드는 스스로를 설명해야 한다는 원칙이 있다. 변수명, 함수명이 명확하면 주석이 적게 필요하다. 하지만 자기 문서화만으로는 부족한 순간이 있다:

# 나쁜 주석 예: "x를 2로 나눈다"
result = x / 2

# 좋은 주석 예: "화면의 물리 픽셀을 논리 픽셀로 변환 (Apple Retina 디스플레이 대응)"
logical_pixel = physical_pixel / 2

변수명만으로는 “왜 2로 나누는가”를 알 수 없다. 이것이 주석의 진정한 역할이다.

코드 의도 읽기의 세 단계

주석이 없거나 부족할 때의 대체 전략을 단계별로 따라가자.
1단계: 코드 자체에서 의도 찾기
테스트 케이스를 먼저 본다. 테스트는 코드가 어떤 입력에 어떤 출력을 반환해야 하는지 보여준다.

# 테스트가 의도를 드러낸다
def test_discount():
    assert calculate_discount(1000, "new") == 1000  # 신규 사용자: 할인 안 함
    assert calculate_discount(1000, "vip") == 800   # VIP: 20% 할인

2단계: Git 기록과 이슈 토론 확인

git log -p --follow -- app/services/payment.py

파일이 언제 왜 수정되었는지 보면 설계 결정의 배경이 드러난다.

commit a3f9e2c: "결제 실패 시 재시도 로직 제거"
- 이유: 결제 게이트웨이 자체가 재시도하므로 중복 제거
- 이전: 무한 루프로 인해 고객 불만 증가

3단계: 숨겨진 제약과 트레이드오프 해석
성능, 호환성, 보안, 법규 때문에 비효율적으로 보이는 코드가 있다:

# 왜 이렇게 복잡한가?
if not user.has_permission("delete") or not user.is_verified():
    # 보안: 검증 안 된 계정이 삭제하지 못하도록 (GDPR 대응)
    log_security_event(user.id)
    raise PermissionDenied()

주석의 부작용: 오래된 주석의 위험

주석은 코드보다 업데이트되지 않기 쉽다. 오래된 주석은 오해를 유발하는 독(毒)이 될 수 있다.

def process_order(order_id):
    # 주석: "주문을 즉시 처리한다"
    # 실제: 비동기 큐에 추가되고 5초 후 처리됨
    
    queue.enqueue(order_id)  # 이미 코드는 변했지만 주석은 그대로

좋은 접근: - 코드를 먼저 신뢰하고, 주석은 왜(Why)를 설명하는 데만 사용 - 주석이 틀렸다면 주석을 수정하지 말고 코드를 명확하게 리팩터링

실무에서의 습관화

주석과 문서를 읽을 때마다 세 가지를 확인하자: 1. 이 결정이 정말 필요한가? (리팩터링 가능성) 2. 이 제약은 언제까지 유효한가? (기술 부채) 3. 이 주석이 코드와 일치하는가? (신뢰성)
이 습관이 쌓이면, 코드의 한두 줄에서도 전체 시스템의 맥락을 읽어낼 수 있다.

---

단어수: 약 1,980자
참고: 원래 개요를 바탕으로 검토 코멘트(사실 오류, 논리 비약, 자기 문서화 개념, 주석의 위험성)를 통합하여 작성했습니다. 추가 개선이 필요하시면 알려주세요.