PEP 257–Docstring Conventions

Python 코드의 docstring 작성에 대한 규칙과 관례를 정의한 문서

  • 정의
    모듈, 함수, 클래스, 메서드 정의의 첫 번째 문장으로 오는 문자열 리터럴로, 해당 객체의 doc 특별 속성이 된다.
  • 작성 대상
    모든 모듈, 모듈이 내보내는 모든 함수와 클래스, 공개 메서드(생성자 포함)에 docstring을 작성해야 한다.
  • 형식
    항상 """삼중 큰따옴표"""를 사용한다.
    한 줄 docstring과 여러 줄 docstring 두 가지 형식이 있다.
    • 한 줄 Docstring
      • 명확한 경우에 사용합니다.
      • 마침표로 끝나는 구문으로 작성합니다.
      • 함수/메서드의 효과를 명령형으로 설명합니다.
    • 여러 줄 Docstring
      • 요약 줄, 빈 줄, 자세한 설명 순으로 구성됩니다.
      • 클래스 docstring 다음에는 빈 줄을 삽입합니다.

기본 규칙

1
2
3
4
5
6
7

def function(arg1, arg2):
    """한 줄 설명.

    여러 줄에 걸친 자세한 설명.
    매개변수와 반환값 설명.
    """
    pass

모듈, 함수, 클래스별 Docstring 내용

모듈

내보내는 클래스, 예외, 함수 등을 나열

1
2
3
4
5
6

"""모듈에 대한 설명.

모듈의 목적과 사용법에 대한 자세한 설명.
"""

import sys

클래스

동작, 공개 메서드, 인스턴스 변수를 나열

1
2
3
4
5
6

class MyClass:
    """클래스에 대한 설명.

    클래스의 목적과 동작 방식에 대한 설명.
    주요 메서드와 속성에 대한 설명.
    """

함수/메서드

동작, 인자, 반환값, 부작용, 예외, 제약사항 등을 문서화

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

def complex_function(param1, param2):
    """함수의 목적을 설명하는 한 줄 요약.

    Args:
        param1 (type): 첫 번째 매개변수 설명
        param2 (type): 두 번째 매개변수 설명

    Returns:
        type: 반환값 설명

    Raises:
        ExceptionType: 예외 발생 조건 설명
    """

참고 및 출처