[Python] Docstring

파이썬은 동적 타입 언어로, 변수에 값을 대입할 때 타입을 명시적으로 선언할 필요가 없습니다.

이는 코드의 유연성과 빠른 개발을 가능하게 해주는 중요한 장점입니다.

하지만, 컴파일 단계에서 타입이 결정되지 않기 때문에 실행 중에 TypeError와 같은 오류가 발생할 가능성이 있습니다.

이러한 파이썬의 동적 특성 때문에, 문서화가 매우 중요하며, 이를 도와주는 기능이 바로 Docstring입니다.

Docstring 이란?

Docstring은 소스 코드에 포함된 주석 형태의 문서로, 코드가 무엇을 하는지 설명합니다. 

파이썬의 모든 함수, 클래스, 모듈 등에 docstring을 작성할 수 있으며, 이는 코드의 가독성과 유지 보수성을 높이는 데 큰 도움을 줍니다. 중요한 점은, docstring은 런타임 중에도 접근할 수 있다는 점입니다. 

이를 통해, 코드를 실행하면서 문서화된 내용을 확인하거나 참조할 수 있습니다.

Docstring 의 형식

Docstring은 크게 두 가지 형식으로 나뉩니다.

1. One-Line Docstring

한 줄짜리 docstring은 간단한 설명을 제공할 때 사용합니다.

보통 함수나 메서드가 간단한 동작을 할 때 적합합니다.

"""로 감싸서 생성하며, 한 줄 안에 필요한 설명을 작성합니다.

def add(a, b):
    """Returns the sum of two numbers."""
    return a + b

2. Multi-Line Docstring

여러 줄로 이루어진 docstring은 함수나 클래스의 동작에 대해 좀 더 상세한 설명이 필요할 때 사용합니다. 

예를 들어, 함수의 파라미터, 반환값, 예외 처리 등의 정보를 포함할 수 있습니다. 

 

아래는 그 예시입니다.

def multiply(a, b):
    """
    Multiplies two numbers and returns the result.
    
    Parameters:
    a (int or float): The first number.
    b (int or float): The second number.
    
    Returns:
    int or float: The product of a and b.
    """
    return a * b

Docstring 접근 방법

파이썬에서는 프로그램을 실행 중에도 문서에 접근할 수 있습니다. 

이를 위해 __doc__이라는 매직 어트리뷰트(magic attribute)를 사용합니다. 

이를 통해 모듈, 클래스, 함수의 docstring을 출력하거나 확인할 수 있습니다.

 

예를 들어, 특정 모듈을 import 한 후, 해당 모듈에 대한 docstring을 확인할 수 있습니다.

import math
print(math.__doc__)

 

이 코드가 실행되면 math 모듈의 docstring이 출력됩니다. 

또한, 모듈 내 함수들의 docstring도 확인할 수 있습니다.

print(math.sqrt.__doc__)

 

실전 예시 : help() 함수와 Docstring

파이썬은 내장 함수인 help()를 통해 모듈이나 함수의 docstring을 간편하게 확인할 수 있는 기능도 제공합니다.

예를 들어, 특정 모듈을 import 한 후, help()를 사용하여 해당 모듈의 모든 함수와 기능에 대한 설명을 볼 수 있습니다.

import math
help(math)

마무리

Docstring은 파이썬에서 코드의 가독성을 높이고, 명확하게 문서화된 코드를 작성하는 데 중요한 역할을 합니다.

이를 통해 함수나 클래스가 하는 일을 쉽게 파악할 수 있으며, __doc__ 또는 help() 함수로 언제든지 문서에 접근할 수 있어 실시간으로 코드 이해를 돕는 도구로 활용됩니다.