파이썬 독스트링 완벽 가이드: 작성법, 스타일, 모범 사례

1. Python의docstring란?

docstring의 위치와 서식

def 함수명(인수):
    """
    여기에 함수에 대한 간단한 설명을 작성합니다.

    인수:
        인수명 (타입): 인수에 관한 자세한 설명
    반환값:
        타입: 반환값에 관한 설명
    """
    pass

2. docstring의 기본적인 작성법

기본적인 docstring의 구조

def add(a, b):
    """두 수를 더해 반환합니다."""
    return a + b

def add(a, b):
    """
    두 수를 더해 그 결과를 반환합니다。

    인수:
        a (int): 더할 첫 번째 수
        b (int): 더할 두 번째 수

    반환값:
        int: 두 수의 합
    """
    return a + b

3. docstring의 스타일（Google 스타일、NumPy 스타일、reStructuredText 스타일）

Google 스타일

def add(a, b):
    """
    두 수를 더해 반환합니다.

    Args:
        a (int): 더할 첫 번째 수
        b (int): 더할 두 번째 수

    Returns:
        int: 두 수의 합
    """
    return a + b

NumPy 스타일

def add(a, b):
    """
    두 수를 더해 반환합니다。

    Parameters
    ----------
    a : int
        더할 첫 번째 수
    b : int
        더할 두 번째 수

    Returns
    -------
    int
        두 수의 합
    """
    return a + b

reStructuredText 스타일

def add(a, b):
    """
    두 수를 더합니다。

    :param a: 더할 첫 번째 수
    :type a: int
    :param b: 더할 두 번째 수
    :type b: int
    :return: 두 수의 합
    :rtype: int
    """
    return a + b

4. PEP 257와 모범 사례

PEP 257의 주요 포인트

1. 한 줄 docstring 간단한 함수나 메서드에는 한 줄로 간결하게 설명을 작성하는 것이 권장됩니다。
2. 여러 줄 docstring 보다 상세한 설명이 필요할 경우에는 여러 줄의 docstring을 사용합니다。 이때 첫 줄은 간단한 요약으로 하고, 이어서 빈 줄을 하나 둔 뒤 자세한 설명을 작성합니다。
3. 들여쓰기와 빈 줄의 활용 docstring 안에서는 줄바꿈과 들여쓰기를 사용해 가독성을 높입니다。 또한 함수의 매개변수와 반환값에 대한 정보는 명확히 구분하여 읽기 쉽도록 정리합니다。

모범 사례

• 간결하고 명확한 설명 docstring은 간결하면서도 함수나 클래스가 무엇을 하는지 정확히 전달해야 합니다。 불필요한 정보는 줄이되, 중요한 부분은 자세히 기술하세요。
• 일관된 스타일 유지 프로젝트 전반에서 docstring의 스타일을 통일하면 가독성이 향상됩니다。 Google 스타일이나 NumPy 스타일 등 팀이나 프로젝트에 가장 적합한 스타일을 선택하세요。

5. docstring을 사용한 테스트(doctest)

doctest의 기본 사용법

def add(a, b):
    """
    두 개의 숫자를 더하여 반환합니다。

    Args:
        a (int): 첫 번째 숫자
        b (int): 두 번째 숫자

    Returns:
        int: 두 숫자의 합

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

doctest를 사용하는 장점

1. 코드의 일관성 doctest를 사용하면 docstring에 적힌 샘플 코드가 실제로 동작하는지 확인할 수 있어, 코드와 문서의 일관성을 유지할 수 있습니다. 이로써 문서가 최신 코드와 항상 일치하는 상태가 유지됩니다。
2. 테스트의 자동화 doctest는 쉽게 자동화할 수 있어 함수나 클래스의 테스트를 수동으로 수행할 필요가 없습니다. doctest를 실행하기만 하면 docstring 안의 모든 코드 예제가 테스트되어 실수를 줄일 수 있습니다。

6. 실전 예：docstring을 활용한 코드의 문서화

클래스에 대한 docstring 작성 예

class Calculator:
    """
    간단한 계산기 클래스.

    이 클래스는 기본적인 덧셈, 뺄셈, 곱셈, 나눗셈을 수행합니다.

    Attributes:
        result (int): 계산 결과를 보관하는 변수
    """

    def __init__(self):
        """
        Calculator 클래스의 생성자.
        초기화 시 결과는 0으로 설정됩니다.
        """
        self.result = 0

    def add(self, a, b):
        """
        두 개의 숫자를 더하고 결과를 반환합니다.

        Args:
            a (int): 첫 번째 숫자
            b (int): 두 번째 숫자

        Returns:
            int: 두 숫자의 합
        """
        self.result = a + b
        return self.result

Sphinx를 사용한 문서 생성

pip install sphinx

7. 자주 하는 실수와 피하는 방법

1. 모호한 설명

def add(a, b):
    """두 숫자를 더합니다."""
    return a + b

def add(a, b):
    """
    두 정수를 더하고 그 결과를 반환합니다.

    Args:
        a (int): 첫 번째 숫자
        b (int): 두 번째 숫자

    Returns:
        int: 두 숫자의 합
    """
    return a + b

2. 인자와 반환값의 부정확한 설명

def divide(a, b):
    """두 숫자를 나눕니다."""
    return a / b

def divide(a, b):
    """
    두 숫자를 나누고 결과를 반환합니다. 0으로 나누면 ZeroDivisionError가 발생합니다.

    Args:
        a (float): 나누어지는 수
        b (float): 나누는 수

    Returns:
        float: 나눗셈 결과

    Raises:
        ZeroDivisionError: 0으로 나누려고 한 경우
    """
    if b == 0:
        raise ZeroDivisionError("0으로는 나눌 수 없습니다")
    return a / b

8. 정리：docstring을 활용한 효율적인 문서 작성

PEP 257에 기반한 일관성 있는 문서 작성

doctest를 활용한 샘플 코드 테스트

Sphinx를 이용한 문서의 자동 생성