코드는 컴퓨터에게 명령을 내리는 동시에 「다른 사람(미래의 자기 자신 포함)에게 의도를 전달하는」 글이기도 합니다.
주석과 docstring은 그 의도를 명확히 적는 두 도구입니다.
주석(comment)은 # 기호로 시작하며, 그 줄 끝까지 컴퓨터가 무시합니다.
# 이 함수는 사용자 나이를 검증한다 같은 식으로 한 줄 설명을 답니다.
여러 줄 주석은 # 를 여러 줄에 적거나, 삼중 따옴표 """...""" 로 감싸는 트릭을 쓰기도 합니다.
docstring은 「함수·클래스·모듈의 첫 줄에 적는 공식적 문서 문자열」입니다.
def greet(name): """인사를 출력한다.
name: 인사할 사람의 이름""" 같은 식.
이 문자열은 help(greet)이나 IDE의 자동 완성에서 즉시 보여집니다.
비유하자면 주석은 「코드 옆의 손글씨 메모」, docstring은 「공식 문서의 표제」와 같습니다.
주석은 자유롭고 가벼운 설명, docstring은 공식적이고 자동 도구가 활용할 수 있는 형식입니다.
좋은 주석의 원칙: 1) 「무엇을」이 아니라 「왜」를 설명 — 코드 자체가 설명하는 사실을 반복하지 말고 그 이유를 적기.
2) 코드 변경 시 주석도 함께 업데이트(잘못된 주석은 없는 주석보다 나쁨).
3) 한 함수가 너무 많은 주석을 필요로 한다면 함수 자체를 나누는 게 좋은 신호.
한 줄 요약
주석은 #로 시작하는 가벼운 설명, docstring은 함수·클래스·모듈의 공식 문서 문자열입니다.
「무엇」이 아닌 「왜」를 설명하는 것이 좋은 주석의 원칙입니다.
더 알아볼 것
- Google·NumPy·Sphinx 스타일 docstring
- Type Hint와 docstring의 관계
- help() 함수와 IDE의 docstring 활용
