[Python] Docstring

Docstring

 파이썬은 자료형이 명시되지 않기 때문에(언어의 동적 특성) 파이썬에서의 문서화는 매우 중요하다.

문서화를 위해서 파이썬은 docstring이라는 문서화 문자열 기능을 제공하고 """ 문서화 문자열입니다. """ 처럼 표현할 수 있다. docstring은 모듈, 클래스, 함수에 붙일 수 있고 각 객체의 __doc__ 속성에 접근하여 문자열을 가져올 수 있다. 어떤 대상에 docstring을 작성할 지에 따라 적어야하는 내용들도 달라진다. 

*더 많은 내용은 https://peps.python.org/pep-0257/ 를 참고

---

 

모듈 docstring

 각 모듈에는 최상위 docstring이 필요하다.

docstring의 첫문장은 모듈의 목적을 기술하는 한 문장으로 구성되며 이후는 모듈의 동작을 자세히 설명한다.

 

예시)

"""
Library for testing

Test Module info

Available functions:
- func1 : test function 1
- func2 : test funtion 2
"""
...

---

 

클래스 docstring

 클래스 수준의 docstring은 모듈 docstring과 거의 비슷하다.

첫 번째 문장에서 클래스의 목적을 기술하고 이후는 동작을 설명한다. 그리고 공개속성과 메서드, 서브클래스가 슈퍼클래스와 상호작용하는 방법등을 안내해야한다.

 

예시)

class Test(object):
"""
Represents a test

class info

Public attributes:
- test_code : test code
- test_result : result
"""
...

---

 

함수 docstring

 함수의 docstring에서는 첫 줄에 수행하는 일, 다음 줄부턴 함수의 특별한 동작이나, 인수에 대한 내용 또는 반환 값을 설명한다. 또한 호출 시 함수 인터페이스에서 처리해야하는 예외도 설명해야 한다.

 

예시)

def Test_func(code):
"""
Testing target

function info

Args:
- code : String of the target Code

Returns:
- Boolean (True if Test is succeed)
"""
...

 

함수가 인수를 받지 않을 경우는 한 줄의 설명으로도 충분하고 아무것도 반환하지 않는다면 Returns는 생략해도 된다.

만약 함수가 가변인수를 사용할 경우, Args 항목에 *args, **kwargs를 적고 목적을 설명해줘야 한다.