[파이썬 코딩의 기술] 02/ 협업의 미덕

 

 

책 『파이썬 코딩의 기술(개정 2판)』 미리 보기

파이썬 코딩의 기술(개정2판)

 

 

BETTER WAY 84/ 모든 함수, 클래스, 모듈에 독스트링을 작성하라

---

다른 언어와 달리 파이썬은 프로그램의 독스트링docstring 에 직접 접근할 수 있다.

def palindrome(word):
	"""주어진 단어가 회문인 경우 True를 반환한다."""
    return word == word[::-1]

assert palindrome('tacocat')
assert not palindrome('banana')

print(repr(palindrome.__doc__))

>>>
'주어진 단어가 회문인 경우 True를 반환한다.'

 

독스트링을 작성할 때에는 몇 가지 따라야 할 지침(PEP 257)이 있다.

모듈 docstring

• 각 모듈에는 소스 코드 맨 첫 줄에서 모듈과 그 내용을 소개하는 docstring이 있어야 한다.
• 다음 단락에는 사용자들이 모듈의 동작에 대해 알아둬야 하는 세부 사항을 적는다.
  예를 들어, 모듈에서 중요한 클래스와 함수를 강조해 알려준다.

 

클래스 docstring

• 첫 줄은 클래스의 목적을 알려주는 문장을 쓴다.
• 다음 단락에는 클래스의 동작 세부 사항 중 중요한 부분을 설명한다.
• 특히 중요한 공개 attribute와 method를 강조한다.
• 만약 해당 클래스를 상속하는 하위 클래스가 있다면 보호 attribute이나 method와 상호작용하는 방법을 가이드한다.

 

함수 docstring

• 첫 줄은 함수가 하는 일을 설명한다.
• 다음 단락에는 함수 argument나 동작, return 값에 대해 구체적으로 설명한다.
  (return 값이 없으면 설명을 제외한다.)
• 함수를 호출할 때 처리해야 하는 예외가 있다면 설명한다.
• 함수가 가변 argument나 keword argument를 받는다면, 각각의 목적을 설명한다.
• 디폴트 값이 있는 argument가 있다면 설명한다.
• 함수가 제너레이터라면, 이를 이터레이션할 때 어떤 값이 발생하는지 설명한다.
• 함수가 비동기 코루틴이라면, 언제 그 실행이 중단되는지 설명한다.

 

from https://lathama.net/Docstring