[파이썬] Docstrings 작성 스타일과 규칙

04 Sep 2023

python

Docstrings은 파이썬 코드에서 함수, 클래스, 모듈 등의 설명을 작성하는데 사용되는 문서화 문자열입니다. 제대로 작성된 Docstrings은 코드의 가독성을 높이고 유지보수와 협업을 용이하게 합니다. 이 글에서는 Docstrings 작성 스타일과 규칙에 대해 알아보겠습니다.

1. Docstrings 작성 위치

함수, 메서드, 클래스, 모듈의 첫 번째 문장으로 작성합니다.
인자와 반환 값의 설명은 해당하는 섹션에 작성합니다.

def greet(name):
    """
    인사말을 출력하는 함수

    :param name: 인사 대상자의 이름
    :type name: str
    :return: 인사말 문자열
    :rtype: str
    """
    return "Hello, " + name

2. Docstrings 작성 스타일

2.1 PEP 257 스타일

PEP 257은 파이썬 Docstrings 작성에 관한 공식적인 스타일 가이드입니다. PEP 257에 따르면 다음과 같은 스타일을 사용합니다:

Docstrings은 “”” “”” (큰 따옴표 3개)나 ‘’’ ‘’’ (작은 따옴표 3개)로 묶습니다.
Docstrings은 의미 있는 문장으로 작성되어야 합니다.

def square(n):
    """
    입력된 숫자의 제곱 값을 반환하는 함수

    :param n: 입력 숫자
    :type n: int
    :return: 입력 숫자의 제곱 값
    :rtype: int
    """
    return n * n

2.2 Google 스타일

Google 스타일은 PEP 257에 비해 좀 더 구체적인 문서화 스타일을 제안합니다. 다음은 Google 스타일의 예제입니다:

def factorial(n):
    """
    주어진 숫자의 팩토리얼 값을 계산합니다.

    Args:
        n (int): 계산할 숫자

    Returns:
        int: 주어진 숫자의 팩토리얼 값
    """
    if n == 0:
        return 1
    else:
        return n * factorial(n-1)

3. Docstrings 작성 요소

Docstrings에는 다양한 요소를 포함할 수 있습니다. 가장 일반적으로 사용되는 요소들은 다음과 같습니다:

Parameters (인자): 함수나 메서드에 전달되는 인자들에 대한 설명
Returns (반환 값): 함수나 메서드가 반환하는 값의 설명
Raises (예외): 호출자가 처리해야 할 예외에 대한 안내
Examples (예제): 함수나 메서드 사용 예제
See Also (참고): 다른 관련 문서나 자료에 대한 링크

def divide(x, y):
    """
    두 숫자를 나눈 결과를 반환합니다.

    :param x: 나뉠 숫자
    :type x: float
    :param y: 나눌 숫자
    :type y: float
    :return: 나눈 결과
    :rtype: float
    :raises ValueError: 0으로 나눌 경우
    :examples:
        divide(10, 2) -> 5.0
        divide(5, 0) -> ValueError
    :see_also: `multiply`, `subtract`
    """
    if y == 0:
        raise ValueError("Cannot divide by zero")
    return x / y

4. Docstrings 자동 생성 도구

Docstrings 작성은 번거로운 작업일 수 있습니다. 자동으로 Docstrings을 생성해주는 도구를 사용하면 이 작업을 효율적으로 수행할 수 있습니다. 대표적인 도구로는 Sphinx, Pydoc, Doxygen 등이 있습니다.

결론

Docstrings은 파이썬 코드의 가독성과 유지보수성을 높이기 위해 중요한 역할을 합니다. 올바른 스타일과 규칙을 따르면 다른 개발자와의 협업에서도 유용하게 사용할 수 있습니다. Docstrings은 코드 작성시 함께 고려해야 하는 중요한 요소 중 하나이므로, 적절한 문서화를 위해 꼼꼼하게 작성해야 합니다.