[Python] 주석(Comment) vs. 독스트링(Docstring) 차이점

서론

기초공부 없이 파이선 개발하다보니 모르는점이 많아 공부하면서 개발중 ㅠㅠ
개념정리겸 포스팅!!
무지렁이는 웁니다.

---

본론

주석(Comment) vs. 독스트링(Docstring) 차이점

Python 코드를 작성하다 보면 함수나 클래스에 대한 설명이 필요할 때가 있고, 반대로 복잡한 코드 흐름이나 예외 처리에 대해 간단히 메모해두고 싶을 때도 있다. 

두 개는 모두 설명을 위한 수단이지만, 용도와 역할이 확실히 다르다는 걸 이해하면 훨씬 더 읽기 좋고 유지보수하기 쉬운 코드를 작성할 수 있다.

---

독스트링 (Docstring) 

독스트링은 """ """ 또는 ''' '''로 감싸진 문자열로, 함수나 클래스, 모듈이 "무엇을 하는지"를 문서화하기 위해 사용

 

사용 목적

• 이 함수(또는 클래스)가 무엇을 하는지 설명
• 다른 개발자 또는 미래의 나 자신이 함수를 이해하는 데 도움
• 자동 문서화 도구(Sphinx, pydoc 등)를 사용할 때 API 문서로 반영 가능

Python 내부적으로 인식함

• help(함수명)을 호출하거나
• 함수명.__doc__ 으로 접근하면 확인 가능

 

예제 (Docstring)

def save_scraped_data(data):
    """ Scraper에서 전송한 data 를 받아서 DB에 저장 """
    # 실제 데이터 저장 로직
    pass

print(save_scraped_data.__doc__)  # ✅ Docstring 확인 가능

 

출력 결과:

Scraper에서 전송한 data 를 받아서 DB에 저장

 

언제 사용하나요?

• 함수 정의 바로 아래에 작성
• 간결하게 작성해도 되지만, 복잡한 함수라면 파라미터, 리턴값, 예외 등도 설명해주는 것이 좋다.

 

고급 Docstring 예시 (PEP 257 스타일):

def send_email(recipient, subject, body):
    """
    이메일을 전송합니다.

    Parameters:
        recipient (str): 수신자 이메일 주소
        subject (str): 이메일 제목
        body (str): 이메일 본문

    Returns:
        bool: 이메일 전송 성공 여부
    """
    # 실제 이메일 전송 로직
    return True

 

---

주석 (Comment)

주석은 코드 안에 # 기호를 사용해 작성되는 간단한 설명으로, Python 인터프리터가 무시하기 때문에 실행에는 영향을 주지 않는다.

사용 목적

• 복잡한 로직에 대해 간단한 설명 추가
• 예외 처리 이유, 특정 조건의 이유 등을 메모
• 협업 시 다른 개발자가 코드를 더 빠르게 이해할 수 있게 도와줌

 

예시:

# 크롤링된 데이터를 데이터베이스에 저장하는 함수
def save_scraped_data(data):
    # 중복 데이터는 저장하지 않도록 체크
    # 저장 전, 데이터 유효성 검사를 먼저 진행해야 함
    pass

 

 

언제 사용하나요?

• 한 줄 또는 여러 줄 주석으로 작성 가능
• 코드 블록 앞이나 로직의 흐름이 바뀌는 시점에 적절히 삽입
• 디버깅 중 임시로 처리한 코드에 이유를 남길 때도 자주 사용

 

인라인 주석도 가능:

total = price * quantity  # 총액 계산 (세금 제외)

---

독스트링 vs. 주석

항목	독스트링(""" """)	주석 (#)
사용 위치	함수, 클래스, 모듈 내부 첫 줄	코드 라인 앞 또는 옆
Python에서 인식	✅ __doc__, help()	❌ 무시됨
용도	문서화, 설명	코드 흐름, 예외 상황 설명
문서 생성 도구 반영	✅ 자동 문서화 가능	❌ 반영 안 됨
실행 시 영향	✅ 내부적으로 저장	❌ 영향 없음
작성 시점	함수/클래스 정의 시	코드 중간 또는 흐름 설명 시
유지보수 도움	함수/클래스의 목적 설명	로직의 구체적인 동작 설명

 

---

상황별로 어떻게 선택해야 할까?

사용 목적	독스트링 사용	주석 사용
함수/클래스 설명	✅ 사용해야 함	❌ 안 씀
반복문, 조건문 설명	❌ 불필요	✅ 로직 해설
예외처리 이유	❌	✅ 꼭 써줘야 함
협업 중 복잡한 코드 설명	❌	✅ 최대한 자세히
API 문서 자동 생성	✅ 필수	❌ 반영 안 됨

---

실무에서 적용

• 함수나 클래스를 만들 때는 항상 Docstring 작성 → 함수의 목적을 설명
• 복잡한 조건, 반복문, 예외 처리 등은 주석으로 흐름 설명 → 이해를 돕는 메모
• 너무 많은 주석은 오히려 가독성이 떨어질수있으니 꼭 필요한 곳에만 작성
• 협업 시에는 주석으로 이유를 남기면 협업에 도움이 됨!

---

마무리

독스트링과 주석은 둘 다 좋은 코드 작성을 위한 필수 도구이지만 상황에 따라 "어디에 어떤 걸 써야 할지"를

정확히 구분해서 사용하는 것 중요하다.

또한 프로젝트 내에 주석에 대한 룰 가이드를 명확하게 제시하는것도 도움이 될 거 같다!!