Python 문서화 (feat. PEP 257)

docstring이란

docstring은 파이썬 코드 내에 있는 문서화 문자열로, 함수, 클래스, 모듈 등의 정의 바로 다음에 나타남

이 문자열은 해당 객체의 역할, 사용법, 매개변수 설명, 반환값 설명 등을 제공하여 코드를 이해하고 사용하는 데 도움이 됨

PEP 257이란

PEP 257은 파이썬 코드의 docstring의 포맷과 사용법에 관한 가이드라인을 제시한 문서

PEP 257의 주요 내용

1. 첫 번째 줄 (요약) : docstring의 첫 번째 줄은 해당 객체(함수, 클래스 등)의 요약 설명을 제공해야 함
2. 두 번째 줄 (빈 줄) : 첫 번째 줄 이후에는 빈 줄을 하나 넣어야 함
3. 자세한 설명 : 이어지는 부분에서는 자세한 설명이 제공되어야 함
4. 매개변수 설명 : 함수의 매개변수에 대한 설명을 포함해야 함
5. 반환값 설명 : 함수의 반환값에 대한 설명을 포함해야 함

PEP 257은 명확하고 이해하기 쉬운 문서에 대한 표준을 제시하기 때문에, PEP 257을 따르면 새로운 개발자들이 코드를 이해하고 활용하기 쉽도록 도와주며 코드의 유지 보수를 용이하게 함

PEP 257을 준수한 docstring 예시

def add(x, y):
    """
    두 숫자의 합을 계산하는 함수

    :param x: 첫 번째 숫자
    :type x: int or float
    :param y: 두 번째 숫자
    :type y: int or float
    :return: 두 숫자의 합
    :rtype: int or float
    """
    return x + y