파이썬 docstring을 사용하는 이유와 방법
파이썬 docstring을 사용하는 이유와 방법
코드를 읽기 쉽고, 유지보수하기 쉬운 방식으로 작성하는 것은 모든 프로그래머에게 중요한 일입니다. 파이썬에서는 이를 돕기 위해 docstring(문서 문자열)이라는 강력한 도구를 제공합니다. Docstring은 함수, 클래스, 모듈 등에 대한 설명을 포함하는 문자열로, 코드에 대한 문서화를 효과적으로 할 수 있게 해줍니다. 이 글에서는 파이썬에서 docstring을 작성하는 이유와 방법을 살펴보겠습니다.
1. Docstring이란?
Docstring은 함수, 클래스, 모듈 등의 요소에 대한 설명을 제공하는 문자열입니다. 이 문자열은 코드의 맨 첫 줄에 작성되며, """(세 개의 큰따옴표)로 감싸서 사용합니다. Docstring은 파이썬 인터프리터에서 함수의 __doc__ 속성을 통해 조회할 수 있으며, 개발자가 코드를 이해하는 데 도움을 줍니다.
def greet(name):
"""
주어진 이름을 입력받아 인사말을 출력하는 함수.
Parameters:
name (str): 인사할 사람의 이름.
Returns:
None
"""
print(f"Hello, {name}!")위 예시에서 함수 greet는 주석이 아닌 docstring을 통해 함수의 목적과 매개변수에 대한 설명을 포함하고 있습니다. 파이썬에서는 이와 같은 방식으로 함수에 대한 정보를 간단하고 명확하게 문서화할 수 있습니다.
2. Docstring을 사용하는 이유
1) 코드 가독성 향상
Docstring의 가장 큰 목적은 코드의 가독성을 높이는 데 있습니다. 주석과는 달리, docstring은 인터프리터에 의해 해석되며, IDE나 도구에서 함수나 클래스를 호출할 때 쉽게 참고할 수 있습니다. 이는 협업 환경에서 코드의 의도를 명확하게 설명하는 데 큰 도움이 됩니다.
def add(a, b):
"""두 숫자의 합을 반환하는 함수."""
return a + b이처럼 간단한 함수라도 docstring을 사용하면 코드의 의도가 명확해집니다. 다른 개발자가 이 함수를 사용할 때 별도의 설명을 찾아보지 않아도 됩니다.
2) 자동화된 문서 생성
Docstring은 다양한 자동화된 문서 생성 도구에서 사용됩니다. 예를 들어, 파이썬의 Sphinx 같은 도구는 docstring을 기반으로 코드의 문서화된 파일을 자동으로 생성합니다. 따라서 코드의 유지보수와 배포를 고려할 때 docstring은 필수적입니다.
3) 개발자 도구와 IDE 지원
많은 IDE(통합 개발 환경)에서 docstring을 기반으로 함수 설명을 자동으로 표시합니다. 예를 들어, 함수의 매개변수를 입력할 때 docstring에 포함된 정보를 툴팁으로 볼 수 있어 개발 속도를 높이는 데 도움을 줍니다.
4) 테스트 및 디버깅에 도움
docstring을 통해 코드를 문서화하면, 나중에 코드를 수정하거나 디버깅할 때 그 의도를 빠르게 파악할 수 있습니다. 특히 큰 프로젝트에서는 이 점이 매우 유용합니다.
3. Docstring 작성 방법
파이썬의 docstring은 다양한 스타일로 작성할 수 있습니다. 가장 기본적인 방법부터, 표준 형식을 따르는 방법까지 살펴보겠습니다.
1) 기본 형태의 Docstring
단순한 함수나 클래스에서는 한 줄로 간단한 설명을 제공할 수 있습니다.
def multiply(a, b):
"""두 숫자의 곱을 반환하는 함수."""
return a * b2) 여러 줄로 작성된 Docstring
복잡한 함수나 클래스에서는 여러 줄에 걸쳐 더 상세한 설명을 제공합니다. 첫 번째 줄은 함수나 클래스의 간략한 설명을 제공하고, 그 다음 줄부터는 매개변수나 반환값에 대한 추가 설명을 포함할 수 있습니다.
def divide(a, b):
"""
두 숫자를 나누어 결과를 반환하는 함수.
Parameters:
a (int or float): 나눌 숫자.
b (int or float): 나누는 숫자. 0이 되어서는 안 됨.
Returns:
float: a를 b로 나눈 결과.
Raises:
ValueError: b가 0일 때 발생.
"""
if b == 0:
raise ValueError("0으로 나눌 수 없습니다.")
return a / b위의 예시에서 docstring은 함수의 입력값, 반환값, 예외 사항에 대해 명확하게 설명하고 있습니다.
3) 클래스와 메서드에 Docstring 작성
클래스에도 docstring을 작성할 수 있습니다. 클래스 docstring은 클래스의 목적과 주요 속성 및 메서드에 대한 설명을 포함합니다.
class Animal:
"""
동물을 나타내는 클래스.
Attributes:
name (str): 동물의 이름.
age (int): 동물의 나이.
"""
def __init__(self, name, age):
"""
Animal 클래스의 생성자.
Parameters:
name (str): 동물의 이름.
age (int): 동물의 나이.
"""
self.name = name
self.age = age
def speak(self):
"""동물이 소리를 낸다."""
print(f"{self.name}가 소리를 냅니다.")클래스 docstring은 클래스 자체를 설명하고, 각각의 메서드에 대해 개별 docstring을 작성함으로써 각 기능의 역할을 문서화할 수 있습니다.
4) Google 스타일과 Numpy 스타일
파이썬 커뮤니티에서는 docstring을 작성할 때 두 가지 주요 스타일을 많이 사용합니다: Google 스타일과 Numpy 스타일입니다.
Google 스타일:
def subtract(a, b):
"""
두 숫자를 빼는 함수.
Args:
a (int or float): 첫 번째 숫자.
b (int or float): 두 번째 숫자.
Returns:
int or float: a에서 b를 뺀 값.
"""
return a - bNumpy 스타일:
def subtract(a, b):
"""
두 숫자를 빼는 함수.
Parameters
----------
a : int or float
첫 번째 숫자.
b : int or float
두 번째 숫자.
Returns
-------
int or float
a에서 b를 뺀 값.
"""
return a - b이 두 스타일은 일관된 형식을 유지하고 문서 생성 도구에 적합하기 때문에 널리 사용됩니다. 특히 대규모 프로젝트에서는 이와 같은 표준 스타일을 따르는 것이 중요합니다.
4. Docstring을 사용하는 방법
작성한 docstring은 파이썬의 내장 함수나 IDE에서 바로 확인할 수 있습니다. 다음과 같이 함수나 클래스의 __doc__ 속성을 통해 docstring을 출력할 수 있습니다.
print(divide.__doc__)또한, 파이썬의 help() 함수를 사용하면 더 구조화된 방식으로 docstring을 확인할 수 있습니다.
help(divide)파이썬의 docstring은 코드의 가독성을 높이고, 자동 문서 생성을 도우며, 코드 유지보수를 쉽게 만들어줍니다. 특히, 협업 환경에서 명확한 설명을 제공함으로써 코드의 의도를 다른 개발자에게 전달하는 데 큰 역할을 합니다. 따라서 파이썬 개발자라면 일관된 docstring 작성 습관을 들여 코드 품질을 향상시키는 것이 중요합니다.