독스트링 작성

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

파이썬은 언어 자체의 동적인 특성으로 인해 문서화가 중요하다.

• 파이썬에서는 프로그램을 실행하는 중에서 프로그램 소스 코드의 문서에 직접 접근할 수 있다.

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

print(repr(palindrome.__doc__)) #독스트링을 가져오려면 __doc__ 특별 애트리뷰트를 사용

• 내장 pydoc 모듈을 사용하여 로컬 웹 서버를 실행할 수 있고 이 서버는 곧 작성한 모듈을 비롯해서 인터프리터에서 찾을 수 있는 모든 파이썬 문서 제공

파이썬의 독스트링과 doc 애트리뷰트 지원의 세 가지 효과

문서에 항상 접근할 수 있기에 대화식 개발이 쉬워진다.

• help 내장 함수를 통해서 함수, 클래스, 모듈의 내부 문서를 살핀다.

• 알고리즘 개발 혹은 API 테스트를하거나 작은 코드를 작성할 때 파이썬 대화식 인터프리터 혹은 IPython 노트북 도구 사용

코드 문서화를 정의하는 표준이 있으므로 문서 본문을 더 보기 좋은 형태로 바꿔주는 도구를 쉽게 만든다.

• 파이썬 커뮤니티 안에서 스핑크스같은 훌륭한 문서 생성 도구가 있다.

• 오픈소스 파이썬 프로젝트들의 보기 좋은 문서들을 무료로 호스팅해주는 리드더덕스같은 사이트도 있다.

파이썬이 제공하는 훌륭하고 접근하기 쉽고 보기 좋은 문서들로 인해서 사람들이 자극 받아서 더 많은 문서 작성

• 좋은 코드란 문서화도 잘된 코드라고 가정이 존재한다.

• 파이썬 오픈 소스 라이브러리들이 좋은 문서를 제공할 것으로 기대해도 좋다.

모듈 문서화하기

• 각 모듈에는 최상위 독스트링이 있어야한다.

• 세 개의 큰 따옴표(""")로 시작하고 목적은 모듈과 모듈 내용을 소개하는 것이다.

• 첫 줄은 모듈의 목적을 설명하는 한 문장

  • 다음 단락은 모듈 사용자들이 모듈의 동작에 대해 알아둬야하는 세부 사항을 적어야 한다.
  • 모듈에서 찾을 수 있는 중요한 클래스와 함수를 강조해서 알려주는 모듈 소개이기도 하다.

• 모듈이 명렬줄 도구라면, 도구를 실행해 사용하는 방법을 모듈 독스트링에 제공하면 좋다.
  

#words.py
#!/usr/bin/env python3
"""단어의 언어 패턴을 찾을 때 쓸 수 있는 라이브러리

여러 단어가 서로 어떤 연관 관계에 있는지 검사하는 것이 어려울 때가 있다!
이 모듈은 단어가 가지는 특별한 특성을 쉽게 결정할 수 있게 해준다.

사용 가능 함수:
- palindrome: 주어진 단어가 회문인지 결정한다.
- check_anagram: 주어진 단어가 어구전철(똑같은 글자들로 순서만 바뀐 경우)인지 결정한다.
...
"""

...

클래스 문서화하기

• 각 클래스는 클래스 수준의 독스트링을 포함해야 한다.

• 클래스 수준 독스트링은 모듈 수준 독스트링과 거의 비슷한 패턴

  • 첫 줄은 클래스 목적을 알려주는 문장이다.
  • 뒤의 단락은 클래스의 동작 세부 사항 중 중요한 부분을 설명한다.

• 독스트링은 클래스에서 중요한 공개 애트리뷰트와 메서드를 강조해서 표시를 해줘야한다.

  • 이 클래스를 상위 클래스로 상속하는 하위 클래스가 보호 애트리뷰트나 메서드와 상호작용하는 방법을 안내해야 한다.

class Player:
	"""게임 플레이어를 표현한다.
    
    하위 클래스는 'tick' 메서드를 오버라이드해사 플레이어의 파워 레벨 등에 맞는 움직임
    애니메이션을 제공할 수 있다.
    
    공개 애트리뷰트:
    - power: 사용하지 않은 파워업들(0과 1사이의 float).
    - coins: 현재 레벨에서 발견한 코인 개수(integer).
   """

함수 문서화하기

• 모든 공개 함수와 메서드에는 독스트링을 포함시켜야 한다.

• 함수나 메서드의 독스트링도 모듈이나 클래스 독스트링과 같은 패턴을 따른다.

  • 첫 줄은 함수가 하는 일을 설명한다.
  • 다음 단락부터는 함수 인자나 함수의 동작에 대해서 구체적으로 설명한다.
  • 반환 값이 있으면 이에 대한 설명도 한다.
  • 꼭 처리해야하는 예외도 설명해야 한다.

def find_anagrams(word, dictionary):
	"""주어진 단어의 모든 어구전철을 찾는다.
    
    이 함수는 '딕셔너리' 컨테이너의 원소 검사만큼 빠른 속도로 실행된다.
    
    Args:
    	word: 대상 단어, 문자열
        dictionary: 모든 단어가 들어 있는 collections.abc.Container 컬렉션
        
    Returns:
    	찾은 어구전철들로 이뤄진 리스트. 아무것도 찾지 못한 경우는 Empty
    """

주요 규칙

• 함수에 인자가 없고 반환 값만 있다면 설명은 한 줄로도 충분하다.

• 함수가 아무 값도 반환하지 않는다면 'return None'이나 None을 반환함이라고 쓰는 것보다 아예 반환 값에 대해 설명을 제외한느 편이 낫다.

• 함수 인터페이스에 예외 발생이 포함되면 발생하는 예외와 예외가 발생하는 상황에 대한 설명을 함수 독스트링에 반드시 포함시켜야 한다.

• 일반적인 동작 중에 함수가 예외를 발생시키지 않을 것을 예상한다면 예외가 발생하지 않는다는 사실을 적지 말라.

• 함수가 가변 인자나 키워드 인자를 받는다면, 문서화한 인자 목록에 *args나 **kwargs를 사용하고 각각의 목적을 설명하라

• 함수에 디폴트 값이 있는 인자가 있다면 디폴트 값을 언급해야한다.

• 함수가 제너레이터라면, 독스트링에는 이 제너레이터를 이터레이션할 때 어떤 값이 발생하는지 기술해야 한다.

• 함수가 비동기 코루틴이라면, 독스트링에 언제 이 코루틴의 비동기 실행이 중단되는지 설명해야 한다.

독스트링과 타입 애너테이션 사용하기

• 정적 분석을 통해서 버그 없애기

• 전형적인 독스트링이 제공하는 정보와 중복될 수 있다.

• 더 이상 독스트링에서 word가 문자열이라고 설명할 필요는 없다.

  • 타입 애너테이션이 이런 정보를 이미 포함하고 있기 때문이다.

from typing import Container, List

def find_anagrams(word: str,
				  dictionary: Container[str]) -> List[str]: 
    """주어진 단어의 모든 어구전철을 찾는다.
    
    이 함수는 '딕셔너리'컨테이너의 원소 검사만큼 빠른 속도로 실행된다.
    
    Args: 
       word: 대상 단어,
       dictionary: 모든 단어가 들어 있는 컬렉션
       
   Returns:
   		찾은 어구전철들
   """

인스턴스 필드, 클래스 애트리뷰트, 메서드 등에서도 마찬가지로 타입 애너테이션과 독스트링의 중복 정보를 피해야 한다.
타입 정보는 가능하다면 어느 한쪽에 몰아서 유지하느 것이 가장 좋다. 왜냐하면, 실제 구현과 문서가 달라질 위험성을 줄일 수 있기 때문이다.

Summary

• 독스트링을 사용해서 모든 모듈, 클래스, 메서드, 함수에 대해 문서를 작성하고 코드를 변경할 때마다 독스트링을 최신 상태로 유지하라.

• 모듈의 경우: 모듈의 내용과 사용자가 알아야 하는 중요한 클래스나 함수를 독스트링에 소개하라

• 클래스의 경우: 동작, 중요한 애트리뷰트, 하위 클래스의 동작 등을 class 문 뒤에 나오는 독스트링에 문서화하라

• 함수와 메서드의 경우: 모든 인자, 반환 값, 발생하는 예외, 기타 세부적인 동작 등을 def문 바로 뒤에 오는 독스트링에 설명하라

• 타입 애너테이션을 사용하는 경우: 타입 애너테이션에 들어 있는 정보를 독스트링에 기술하지 말라. 타입 애너테이션과 독스트링에 모두 타입 정보를 기술하는 것은 불필요한 중복 작업이다.