python docstring 작성법

docstring은 Python에서 함수, 클래스, 메서드, 모듈 등에 대한 설명을 작성하는 표준 방법입니다. 이는 코드의 가독성을 높이고, 다른 개발자들이나 자신이 나중에 코드를 볼 때 쉽게 이해할 수 있도록 돕습니다. Python은 docstring을 따로 문서화된 문자열로 관리하고, 이를 help() 함수나 IDE에서 볼 수 있게 제공해줍니다.

1. docstring 기본 형식

docstring은 함수나 클래스 바로 아래에 삼중 따옴표 (""" """)로 작성합니다. 기본적인 형식은 아래와 같습니다:

def my_function():
    """
    함수에 대한 설명을 작성합니다.
    이곳에 함수의 목적과 사용 방법을 설명할 수 있습니다.
    """
    pass

docstring은 함수의 첫 번째 줄에 짧은 설명을, 그 아래에 추가 설명을 넣을 수 있습니다.

2. docstring의 기본 규칙

• 첫 번째 줄: 함수의 목적을 간단하고 명확하게 설명합니다. 이 줄은 간결하고 직관적으로 작성되어야 합니다.
• 빈 줄: 첫 번째 설명 뒤에는 빈 줄을 추가하여 추가 설명을 구분합니다.
• 추가 설명: 두 번째 줄 이후에는 더 상세한 설명을 추가합니다. 예를 들어 함수의 매개변수, 반환 값, 예외 처리 등에 대해 설명할 수 있습니다.

3. docstring 예시

(1) 간단한 함수에 대한 docstring

def add(a, b):
    """
    두 숫자의 합을 구합니다.

    :param a: 더할 첫 번째 숫자 (int)
    :param b: 더할 두 번째 숫자 (int)
    :return: 두 숫자의 합 (int)
    """
    return a + b

• 첫 번째 줄: 함수의 목적을 간단히 설명합니다.
• 빈 줄: 추가 설명을 구분하는 빈 줄입니다.
• param: 매개변수에 대한 설명을 :param <이름> 형식으로 작성합니다. 매개변수의 이름과 타입을 명시합니다.
• return: 반환 값에 대해 설명하는 부분입니다. :return을 사용하여 반환값의 타입과 의미를 설명합니다.

(2) 더 복잡한 함수에 대한 docstring

def clickable(selector: str, second: int = 1) -> None:
    """
    주어진 CSS 셀렉터에 해당하는 요소가 클릭 가능해질 때까지 기다립니다.

    이 함수는 WebDriverWait을 사용하여 최대 `second` 초 동안 요소가 클릭 가능해질 때까지 기다립니다.
    만약 요소가 클릭 가능해지지 않으면, 예외가 발생하지 않고 `None`을 반환합니다.

    :param selector: 클릭할 요소의 CSS 셀렉터 (str)
    :param second: 대기할 최대 시간 (초), 기본값은 1초 (int)
    :return: None
    :raises TimeoutException: 요소가 클릭 가능해지지 않으면 타임아웃 예외 발생
    """
    try:
        WebDriverWait(driver, second).until(
            expected_conditions.element_to_be_clickable(
                (By.CSS_SELECTOR, selector)
            )
        )
    except TimeoutException:
        pass

4. 다양한 docstring 스타일

docstring을 작성할 때 사용하는 스타일은 몇 가지가 있습니다. 가장 일반적으로 사용되는 스타일을 두 가지 소개하겠습니다.

(1) Google 스타일

Google 스타일은 매우 직관적이고 간단한 문서화 스타일입니다.

def clickable(selector: str, second: int = 1) -> None:
    """
    주어진 CSS 셀렉터에 해당하는 요소가 클릭 가능해질 때까지 기다립니다.

    Args:
        selector (str): 클릭할 요소의 CSS 셀렉터.
        second (int): 대기할 최대 시간 (초). 기본값은 1초.

    Returns:
        None

    Raises:
        TimeoutException: 요소가 클릭 가능해지지 않으면 타임아웃 예외 발생.
    """
    try:
        WebDriverWait(driver, second).until(
            expected_conditions.element_to_be_clickable(
                (By.CSS_SELECTOR, selector)
            )
        )
    except TimeoutException:
        pass

• Args: 매개변수에 대한 설명.
• Returns: 반환 값에 대한 설명.
• Raises: 함수가 발생시킬 수 있는 예외에 대한 설명.

(2) NumPy 스타일

NumPy 스타일은 수학적, 과학적 코드에 많이 사용되며, 함수와 메서드에 대한 문서화에 적합합니다.

def clickable(selector: str, second: int = 1) -> None:
    """
    주어진 CSS 셀렉터에 해당하는 요소가 클릭 가능해질 때까지 기다립니다.

    Parameters
    ----------
    selector : str
        클릭할 요소의 CSS 셀렉터.
    second : int, optional
        대기할 최대 시간 (초), 기본값은 1초.

    Returns
    -------
    None

    Raises
    ------
    TimeoutException
        요소가 클릭 가능해지지 않으면 타임아웃 예외 발생.
    """
    try:
        WebDriverWait(driver, second).until(
            expected_conditions.element_to_be_clickable(
                (By.CSS_SELECTOR, selector)
            )
        )
    except TimeoutException:
        pass

• Parameters: 매개변수에 대한 설명을 type과 함께 설명합니다.
• Returns: 반환 값에 대한 설명.
• Raises: 예외에 대한 설명.

5. docstring을 활용한 도움말 보기

작성한 docstring은 help() 함수를 사용하여 언제든지 볼 수 있습니다.

help(clickable)

이렇게 하면, clickable 함수에 작성한 docstring을 볼 수 있습니다.

6. docstring의 장점

• 가독성: 함수나 클래스의 목적과 사용법을 쉽게 이해할 수 있습니다.
• 자동화 도구: help() 함수나 IDE에서는 docstring을 활용해 함수를 더 쉽게 사용할 수 있도록 돕습니다.
• 유지보수성: 코드 작성자가 아닌 다른 개발자가 코드를 이해하고 사용할 때 유용합니다.

결론

• docstring 작성은 Python에서 코드의 문서화를 표준화된 형식으로 제공하는 중요한 작업입니다.
• 함수를 작성할 때마다 간단한 설명과 매개변수, 반환값, 예외 처리 등을 docstring으로 작성하면 코드의 가독성과 유지보수성을 높이는 데 큰 도움이 됩니다.
• 다양한 스타일을 사용할 수 있으며, 프로젝트나 팀에서 일관된 스타일을 사용하는 것이 좋습니다.