[Python] Tip - 모든 함수, 클래스, 모듈에 docstring을 작성

파이썬에서 문서화는 언어의 동적 특성 때문에 극히 중요합니다. 파이썬은 코드 블록에 문서를 첨부하는 기능을 기본으로 지원합니다. 대부분의 다른 언어와는 다르게 프로그램 실행 중에 소스 코드에 첨부한 문서에 직접 접근할 수 있습니다.

예를 들어 함수의 def 문 바로 다음에 docstring을 직접 작성하여 문서를 추가할 수 있습니다.

def palindrome(word): """ Return True if the given word is a palindrome. """ return word == word[::-1] # 함수의 __doc__라는 특별한 속성에 접근하면 파이썬 프로그램 자체에 포함된 docstring을 추출할 수 있음 print(repr(palindrome.__doc__)) # 결과 # '\n Return True if the given word is a palindrome.\n '

파이썬은 docstring과 __doc__ 속성을 지원하는 덕분에 다음 세 가지 효과를 얻습니다.

1. 문서의 접근성 덕분에 대화식으로 개발하기 더 쉽습니다. 내장 함수 help로 함수, 클래스, 모듈을 조사하여 문서를 볼 수 있습니다.
2. 문서를 정의하는 표준 방법이 있으면 텍스트를 더 쉽게 이해할 수 있는 포맷(HTML 같은)으로 변환하는 도구를 쉽게 만들 수 있습니다. 그래서 파이썬 커뮤니티의 Sphinx와 같은 훌륭한 문서 생성 도구가 생겨났습니다. 또한 오픈 소스 파이썬 프로젝트의 멋진 문서를 무료로 제공하는 Read the Docs와 같은 커뮤니티 펀딩 사이트도 생겼습니다.
3. 파이썬의 일급 클래스(first-class), 접근성, 잘 정리된 문서는 사람들이 문서를 더 많이 작성할 수 있도록 북돋아줍니다. 파이썬 커뮤니티의 멤버들은 문서화가 중요하다고 강하게 믿고 있습니다. 

모듈 문서화

각 모듈에는 최상위 docstring이 있어야 합니다. 최상위 docstring은 소스 파일에서 첫 번째 문장에 있는 문자열입니다. 최상위 docstring에는 큰 따옴표 세 개(""")를 사용해야 합니다. 이 docstring의 목적은 모듈과 모듈의 내용에 대한 소개입니다.

docstring의 첫 번째 줄은 모듈의 목적을 기술하는 한 문장으로 구성해야 합니다. 그 이후의 문단은 모듈이 모든 사용자가 알아야 하는 모듈의 동작을 자세히 설명한 내용을 포함합니다. 또한 모듈 docstring은 모듈 내의 중요 클래스나 함수를 강조하는 중요한 부분입니다.

"""Criteria to select ServerDescriptions based on maxStalenessSeconds. The Max Staleness Spec says: When there is a known primary P, a secondary S's staleness is estimated with this formula: (S.lastUpdateTime - S.lastWriteDate) - (P.lastUpdateTime - P.lastWriteDate) + heartbeatFrequencyMS When there is no known primary, a secondary S's staleness is estimated with: SMax.lastWriteDate - S.lastWriteDate + heartbeatFrequencyMS where "SMax" is the secondary with the greatest lastWriteDate. """   # ...

클래스 및 함수 문서화

클래스와 함수 또한 모듈 문서화와 유사합니다. 클래스 및 함수 바로 아래에 큰 따옴표 세 개(""")를 사용하여 작성합니다.  또한 첫 번째 줄은 클래스 및 함수의 목적, 수행하는 일에 대해 한 문장으로 설명합니다. 그 다음 문단에서는 동작이나 인수에 대해 설명합니다. 함수의 경우 return 값도 언급해야합니다.

def palindrome(word): """ Return True if the given word is a palindrome. """ #...   class Test: """ test class """

함수의 docstring을 작성할 때 알아둬야 할 몇 가지 특별한 경우가 있습니다.

• 함수가 인수는 받지 않고 간단한 값만 반환할 때는 한 줄짜리 설명으로 충분
• 함수가 아무것도 반환하지 않는다면 return none이라고 하기 보단 반환값을 언급하지 않는 것이 나음
• 함수가 일방적인 동작에서는 예외를 일으키지 않는다고 생각한다면 이에 대해서는 언급하지 않는 것이 나음
• 함수가 받는 인수의 개수가 가변적이거나 키워드 인수를 사용한다면 순서의 인수목록에 *args와 **kwargs를 사용해서 그 목적을 설명
• 함수가 기본값이 있는 인수를 받는다면 해당 기본값을 설명해야 함
• 함수가 제너레이터라면 제너레이터가 순회될 때 무엇을 넘겨주는지 docstring으로 설명해야 함
• 함수가 코루틴이라면 코루틴이 무엇을 넘겨주는지, yield 표현식으로부터 무엇을 얻는지, 언제 순회가 끝나는지를 docstring으로 설명해야 함

요약

모듈의 docstring을 작성한 후에는 문서를 계속 업데이트하는 게 중요. 내장모듈 doctest는 docstring에 포함된 사용 예제를 실행하기 쉽게 해줘서 사용자가 작성한 소스코드와 문서가 시간이 지나면서 여러 버전으로 나뉘지 않게 해줌 모듈: 모듈의 내용과 모든 사용자가 알아둬야 할 중요한 클래스와 함수를 설명 클래스: class 문 다음의 docstring에서 클래스의 동작, 중요한 속성, 서브클래스의 동작을 설명 함수와 메서드: def 문 다음의 docstring에서 모든 인수, 반환 값, 일어나는 예외, 다른 동작들을 문서화