[Python] Docstring에 대해 알아보자

안녕하세요, 오늘은 Python에서 사용하는 Docstring에 대해 설명해드릴려고 합니다. 

Docstring이란?

---

Docstring은 Python에서 함수, 클래스, 모듈이나 메소드 등 첫 번째 줄에 위치하며, 코드의 목적이나 동작을 설명하는데 사용됩니다. 파이썬의 help함수를 이용해서 Docstring에 접근할 수 있으며, 코드의 이해를 돕고 다른 개발자들이 코드를 더 쉽게 사용할 수 있도록 합니다.

예시

>>> help(len)                                                                                                                

len(obj, /)
    Return the number of items in a container.

 

Docstring 기본 구조

---

• 함수나 메소드의 Docstring: 함수의 작동 방식, 매개변수, 반환 값, 발생할 수 있는 예외 등을 설명합니다.
• 클래스의 Docstring: 클래스의 목적과 행동을 설명하고, 주요 메소드에 대한 간단한 요약을 포함할 수 있습니다.
• 모듈의 Docstring: 모듈의 콘텐츠와 모듈이 제공하는 주요 클래스와 함수를 개략적으로 설명합니다.

 

Docstring 사용 예시

---

작성은 Module 첫번째 줄, 선언 후 바로 아랫줄에 작은따옴표 3개 또는 큰 따옴표 3개를 이용해서 작성합니다.

간단한 add 함수를 이용해서 사용해보겠습니다.

def add(a, b):
    """
    두 수의 합을 반환합니다.

    매개변수:
        a (int): 첫 번째 숫자.
        b (int): 두 번째 숫자.

    반환값:
        int: a와 b의 합.

    예외:
        TypeError: 입력된 매개변수가 정수가 아닐 때 발생.

    사용 예:
        >>> add(2, 3)
        5
    """
    return a + b

• help 함수를 사용하기
• __doc__ 속성 사용하기

2가지를 이용해 실행해보겠습니다.

실행결과 1

>>> help(add)
Help on function add in module __main__:

add(a, b)
    두 수의 합을 반환합니다.

    매개변수:
        a (int): 첫 번째 숫자.
        b (int): 두 번째 숫자.

    반환값:
        int: a와 b의 합.
                                                                                                                                                                
    예외:
        TypeError: 입력된 매개변수가 정수가 아닐 때 발생.

    사용 예:
        >>> add(2, 3)
        5

실행결과 2

>>> add.__doc__
'\n    두 수의 합을 반환합니다.\n\n    매개변수:\n        a (int): 첫 번째 숫자.\n        b (int): 두 번째 숫자.\n\n    반환값:\n        int: a와 b의 합.\n\n    예외:\n        TypeError: 입력된 매개변수가 정수가 아닐 때 발생.\n\n    사용 예:\n        >>> add(2, 3)\n        5\n    '

다음과 같이 함수에 대한 설명이 실행결과로 나옵니다.

 

결론

---

docstring을 이용해 다음과 같이 함수의 설명, 매개변수 설명과 사용 예시를 설명할 수 있습니다.