파이썬 프로그램에서는 코드의 각 부분을 이해하기 쉽도록 주석(Comment)을 달 수 있습니다. 하지만 주석만 사용하면 필요한 설명을 찾으려면 검색(Ctrl+F)을 하거나 수십 줄을 스크롤해야 하고, 특정 설명이 코드의 어느 부분과 연결되어 있는지 한눈에 파악하기 어렵습니다. 이러한 불편함을 해소하기 위해 파이썬은 독스트링(Docstring)이라는 공식적인 문서화 방식을 제공합니다. 독스트링은 함수, 모듈, 클래스, 메서드 정의 바로 아래에 작성하는 문자열로, 코드와 문서를 하나로 묶어 관리할 수 있게 해줍니다.
독스트링 출력하기 — __doc__ 속성
객체 정의 바로 다음 줄에 문자열을 작성하면, 파이썬 인터프리터는 이를 자동으로 해당 객체 이름의 __doc__ 속성에 연결합니다. 따라서 별도의 도구 없이도 객체이름.__doc__ 형태로 언제든 설명을 조회할 수 있습니다.
예제
def add_nums(x):
'''숫자를 자기 자신에게 더해 두 배로 만듭니다.'''
return x + x
print(add_nums.__doc__)
출력 결과
위 코드를 실행하면 다음과 같은 결과를 얻습니다.
숫자를 자기 자신에게 더해 두 배로 만듭니다.
한 줄(Single-line) 독스트링
한 줄 독스트링은 말 그대로 한 줄로 요약된 설명입니다. 지나치게 길거나 장황하지 않아야 하며, 문자열의 시작과 끝을 삼중 따옴표(''' 또는 """)로 감싸야 합니다. 위 예제의 독스트링이 대표적인 한 줄 독스트링입니다.
여러 줄(Multi-line) 독스트링
모듈이나 함수의 동작을 더 자세히 설명해야 할 때는 여러 줄 독스트링을 사용합니다. 첫 줄에는 한 줄 독스트링처럼 짧은 요약을 적고, 한 줄을 비운 뒤 그 아래에 더 구체적인 설명을 덧붙이는 것이 표준적인 작성 방식입니다.
예제
def fibonacci(n):
'''피보나치 수열의 n번째 값을 반환합니다.
피보나치 수는 다음 정수 수열에 나타나는 수입니다.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, ...
'''
if n <= 1:
return n
return fibonacci(n - 1) + fibonacci(n - 2)
print(fibonacci.__doc__)
출력 결과
위 코드를 실행하면 다음과 같은 결과를 얻습니다.
피보나치 수열의 n번째 값을 반환합니다. 피보나치 수는 다음 정수 수열에 나타나는 수입니다. 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, ...
내장 객체의 독스트링 확인하기
파이썬에 내장된 함수, 모듈, 클래스 등의 설명 역시 같은 방식으로 손쉽게 조회할 수 있습니다. 객체 이름 뒤에 __doc__을 붙여 출력하기만 하면 됩니다.
예제
print(list.__doc__)
출력 결과
위 코드를 실행하면 다음과 같은 결과를 얻습니다.
Built-in mutable sequence. If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.
즉, list 객체는 "인자가 없으면 새 빈 리스트를 생성하고, 인자가 지정된 경우에는 반복 가능한(iterable) 객체여야 한다"고 설명하고 있습니다.
독스트링의 들여쓰기 규칙
독스트링 첫 번째 줄(첫 개행 문자 이전까지)의 들여쓰기는 의미가 없으므로 자동으로 제거됩니다. 반면 두 번째 줄 이후의 상대적인 들여쓰기는 그대로 유지됩니다. 따라서 전체 독스트링은 첫 줄의 따옴표 위치와 동일한 수준으로 들여써야, 나중에 문서를 출력했을 때 깔끔하게 정렬됩니다.
추가 팁: help() 함수로 문서 보기
help() 내장 함수를 사용하면 독스트링을 더 보기 좋은 형태로 확인할 수 있습니다. help(add_nums) 또는 help(list)처럼 호출하면 객체의 독스트링이 자동으로 정리되어 출력됩니다. 또한 PEP 257 문서에서는 요약 줄 작성, 마침표 사용 등 독스트링 작성 규칙을 권장하고 있으므로, 표준 라이브러리의 스타일을 참고해 일관성 있게 작성하는 것이 좋습니다.