파이썬 Docstring 으로 문서화하기

Introduction

Docstring은 파이썬에서 코드 문서화의 중심에 있는 기능입니다.

코드 문서화는 좋은 프로그램의 필수적 요소입니다. 아무리 성능이 훌륭한 코드여도 문서를 잘 갖추지 않는다면 사람들은 사용하지 않을 것 이기 때문입니다.

 

Commenting vs Documenting Code

• Comment: 주석은 코드를 개발자들에게 설명하기 위해서 사용.
  • "코드는 '어떻게'를 알려주고, 주석은 '왜'를 알려줍니다.” - Jeff Atwood
  • 코드 주석을 작성하는 목적은 계획 및 검토, 코드 설명, 알고리즘 설명, 태깅 등 여러 가지
  • 주석은 구체적인 코드 라인이나 블록 바로 근처에 존재.
  • PEP 8에 따르면 주석은 최대 72자까지여야 합니다.
• Documenting Code: 코드를 문서화하는 것은 사용자에게 코드의 용도와 기능을 설명하는 것입니다.  있지만, 주요 이용자는 사용자(함수의 사용자, 클래스의 사용자 등)입니다. 파이썬에서는 docstrings을 이용해서 코드를 문서화할 수 있습니다.

 

Docstring

파이썬에서 문서화를 하는 방법의 중심에는 Docstrings가 있습니다. 파이썬 객체에 built-in string으로 포함되어 있어 적절하게 이용하면 사용자에게 도움을 줄 수 있습니다.

또한 파이썬에는 객체의 독스트링을 콘솔에 출력하는 내장 함수인 help()가 있습니다. 여기 간단한 예시가 있습니다.

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.

파이썬에는 독스트링 생성을 단순화하는 또 다른 기능이 있습니다. 객체(module, class, function) 바로 아래에 문자열 리터럴을 생성하면 __doc__ 값이 자동으로 설정됩니다. 위의 예시를 같은 방식으로 사용하면 다음과 같습니다.

>>> def do_document():
...   ''' document is so important'''
...   print("okay")
...
>>> help(do_document)

Help on function do_document in module __main__:

do_document()
    document is so important

즉, 파이썬에서 모든 생성하는 함수나 클래스에 docstring을 생성해서 사용자에게 함수와 클래스에 대해서 설명할 수 있습니다.

 

Docstring 스타일

Docstring에는 여러 가지 스타일이 존재하는데 대표적인 포맷팅들은 아래와 같습니다.

Formatting Type	Description	Supported by Sphynx	Formal Specification
Google docstrings	Google’s recommended form of documentation	Yes	No
reStructuredText	Official Python documentation standard; Not beginner friendly but feature rich	Yes	Yes
NumPy/SciPy docstrings	NumPy’s combination of reStructuredText and Google Docstrings	Yes	Yes
Epytext	A Python adaptation of Epydoc; Great for Java developers	Not officially	Yes

저는 이 중에 Google docstring를 선호하는데 그 이유는 아래와 같습니다.

- arguments와 return value의 type을 문서화하지 않고, type hint를 사용. -> 반복을 줄이고, 유지 보수성을 높입니다.

- 다른 format에 비해 document code line 수가 적어서 코드 읽기가 좋습니다. -> 문서가 너무 길면 코드 읽기가 어렵다고 생각합니다.

 

Reference

- https://realpython.com/documenting-python-code/#docstring-types (읽어보시길 추천드립니다!)

- https://peps.python.org/pep-0257/