[PYTHON] 주석(Comment)을 다는 가장 좋은 방법은? 클린 코드를 위한 가이드

주석(Comment)

 

파이썬은 그 자체로 '읽기 쉬운' 언어를 지향합니다. 하지만 복잡한 비즈니스 로직이나 알고리즘 속에서 코드만으로는 설명되지 않는 맥락이 존재하기 마련입니다. 초보 개발자는 코드를 설명하기 위해 주석을 달고, 숙련된 개발자는 코드로 설명되지 않는 의도(Intent)를 전달하기 위해 주석을 사용합니다. 본 포스팅에서는 파이썬의 철학에 부합하면서도 협업 효율을 극대화할 수 있는 최고의 주석 작성 전략을 심층적으로 다룹니다.

---

1. 좋은 주석의 철학: Less is More

가장 좋은 주석은 '주석이 필요 없는 코드'입니다. 변수명과 함수명을 명확하게 지었다면 코드는 스스로를 설명해야 합니다. 하지만 다음과 같은 상황에서는 반드시 주석이 필요합니다.

• 결정의 이유: 왜 다른 대안 대신 이 방법을 선택했는가?
• 복잡한 비즈니스 로직: 코드만으로 파악하기 힘든 실제 업무 규칙
• 함정 경고: 특정 코드를 수정했을 때 발생할 수 있는 부작용(Side-effects)
• 외부 참조: 특정 공식이나 문서의 링크

---

2. 파이썬 주석 유형별 작성 전략

파이썬에서 사용하는 주석의 종류와 각각의 최적 활용법을 정리했습니다.

주석 유형	작성 방법	권장 사용 사례
한 줄 주석 (Inline)	# 뒤에 한 칸 띄우고 작성	복잡한 수식의 의미나 임시 플래그 설명
블록 주석 (Block)	코드와 동일한 들여쓰기 수준 유지	함수나 클래스 내부의 복잡한 로직 흐름 설명
Docstring	""" 내용 """ (세 개 따옴표)	모듈, 클래스, 메서드의 API 문서화 (필수)
TODO 주석	# TODO: 키워드 사용	향후 개선 사항이나 미구현 기능 표시

---

3. 절대 피해야 할 '나쁜 주석' 사례

오히려 코드 가독성을 해치는 주석은 지양해야 합니다.

1. 코드 복사 주석: i = i + 1 # i에 1을 더함 (설명할 가치가 없는 당연한 내용)
2. 과거 기록 주석: Git과 같은 버전 관리 시스템이 해결할 문제를 주석으로 남기는 행위
3. 변명 주석: "이 코드는 엉망이지만 나중에 고치겠다"는 식의 무책임한 주석

---

4. Sample Example: Bad vs Good

실제 예시를 통해 주석의 질이 어떻게 코드의 가치를 바꾸는지 확인해보세요.

[Bad Case] 불필요한 정보의 나열

# 리스트에서 숫자를 찾아 리턴함
def find_num(l, n):
    for i in l: # 루프 시작
        if i == n: # 숫자가 같으면
            return True # 트루 리턴
    return False

[Good Case] 의도와 명세를 명확히 한 주석

def contains_element(elements: list, target: int) -> bool:
    """
    대상 리스트에서 특정 정수의 존재 여부를 확인합니다.
    
    Args:
        elements: 검색 대상 정수 리스트
        target: 찾고자 하는 목표 정수
    Returns:
        존재 여부에 따른 Boolean 값
    """
    # 선형 탐색을 사용함 (데이터셋이 100개 미만이므로 정렬 후 이진 탐색보다 효율적)
    for item in elements:
        if item == target:
            return True
    return False

---

5. 실전 팁: Google Python Style Guide 준수하기

글로벌 표준인 Google Style Guide에 따르면, 주석은 문장으로 작성하며 첫 글자는 대문자로, 마침표로 끝내는 것을 권장합니다. 또한, 코드와 주석 사이에는 최소 두 칸의 공백을 두어 시각적으로 분리하는 것이 좋습니다.

---

6. 내용의 출처

• PEP 8 – Style Guide for Python Code (python.org)
• Google Python Style Guide (google.github.io)
• Clean Code (Robert C. Martin)
• Python Software Foundation Documentation