파이썬 - 독스트링

안녕하세요, 파이썬 프로그래머를 꿈꾸고 계신 분들! 오늘은 우리가 독스트링의 놀라운 세계에 몸을 던지기 위해 다이브를 합니다. 친절한 이웃 컴퓨터 과학 교사로서, 파이썬 프로그래밍의 이 중요한 측면을 안내해드리게 되어 기쁩니다. 그럼, 좋아하는 음료를 준비하고 편하게 앉아서, 이 학습 모험에 함께 떠나보겠습니다!

파이썬에서의 독스트링

일기를 쓰는 것을 상상해보세요. 각 기록의 시작에는 그날 일어난 일에 대한 간략한 요약을 적을 수 있습니다. 파이썬의 독스트링은 그런 것과 비슷합니다! 그들은 코드가 무엇을 하는지 설명하는 특별한 문자열이며, 나중에 자신의 코드를 이해하는 데 (그리고 다른 사람들도) 더 쉽게 만듭니다.

파이썬에서는 독스트링을 삼중 따옴표(""" 또는 ''')로 둘러싸고, 함수, 클래스, 또는 모듈 정의 바로 뒤에 배치합니다. 간단한 예제를 살펴보겠습니다:

def 인사하기(이름):
"""이 함수는 파라미터로 전달된 사람에게 인사합니다"""
print(f"안녕, {이름}!")

이 예제에서, 삼중 따옴표 사이의 줄은 우리의 독스트링입니다. 이 함수가 무엇을 하는지 간단히 설명합니다.

단일 줄 독스트링

단순한 함수나 클래스의 경우, 단일 줄 독스트링이 충분할 수 있습니다. 다른 예제를 보겠습니다:

def 제곱(n):
"""숫자의 제곱을 반환합니다."""
return n ** 2

이 독스트링은 짧고 써먹고, 함수가 무엇을 하는지 단 한 줄로 설명합니다.

다중 줄 독스트링

더 복잡한 함수나 클래스의 경우, 다중 줄 독스트링이 필요할 수 있습니다. 이들은 일반적으로 요약 줄 하나, 빈 줄 하나, 그리고 더 자세한 정보로 구성됩니다. 예를 보겠습니다:

def 면적_계산(length, width):
"""
직사각형의 면적을 계산합니다.

Parameters:
length (float): 직사각형의 길이
width (float): 직사각형의 폭

Returns:
float: 직사각형의 면적
"""
return length * width

이 다중 줄 독스트링은 함수의 파라미터와 반환하는 것에 대한 더 자세한 정보를 제공합니다.

모듈에 대한 독스트링

모듈도 독스트링을 가질 수 있습니다! 이들은 파일의 맨 앞에 배치됩니다. 예를 들어:

"""
이 모듈은 기하학적 계산을 위한 유틸리티 함수를 포함합니다.
각형의 면적과 부피를 계산하는 함수가 포함됩니다.
"""

def 원_면적_계산(radius):
# 함수 구현이 여기에 있습니다

클래스에 대한 독스트링

클래스도 독스트링을 가질 수 있습니다. 이들은 클래스 정의 바로 뒤에 배치됩니다:

class 직사각형:
"""
직사각형을 나타내는 클래스입니다.

Attributes:
length (float): 직사각형의 길이
width (float): 직사각형의 폭
"""

def __init__(self, length, width):
self.length = length
self.width = width

독스트링 접근

독스트링의 멋진 점 중 하나는 프로그래ム적으로 접근할 수 있다는 것입니다. 파이썬은 독스트링을 함수, 클래스, 또는 모듈의 __doc__ 어트리뷰트로 저장합니다. 이렇게 접근할 수 있습니다:

def 인사하기(이름):
"""이 함수는 파라미터로 전달된 사람에게 인사합니다"""
print(f"안녕, {이름}!")

print(인사하기.__doc__)

이것은 다음과 같은 출력을 날립니다: 이 함수는 파라미터로 전달된 사람에게 인사합니다

독스트링 작성의 최상의 관행

이제 우리는 독스트링을 어떻게 작성하는지 알았으니, 몇 가지 최상의 관행에 대해 이야기해보겠습니다:

1. 간결하지만 정보를 제공하십시오
2. 올바른 문법과 구두점을 사용하십시오
3. 스타일에 일관성을 유지하십시오
4. 함수에 대한 파라미터와 반환 값에 대한 정보를 포함하십시오
5. 클래스의 경우 중요한 어트리뷰트와 메서드를 설명하십시오

구글 스타일 독스트링

구글은 자신의 독스트링 스타일 가이드를 가지고 있습니다. 예를 들어:

def 나누기(a, b):
"""두 숫자를 나눕니다.

Args:
a (int): 피제수.
b (int): 제수.

Returns:
float: 나눗셈의 결과.

Raises:
ZeroDivisionError: b가 0인 경우.
"""
if b == 0:
raise ZeroDivisionError("0으로 나눌 수 없습니다")
return a / b

NumPy/SciPy 스타일 독스트링

과학적 파이썬 라이브러리를 사용하는 경우, NumPy/SciPy 스타일을 마주할 수 있습니다:

def 평균_계산(numbers):
"""
숫자의 목록의 산수 평균을 계산합니다.

Parameters
----------
numbers : list
숫자의 목록.

Returns
-------
float
입력 목록의 산수 평균.
"""
return sum(numbers) / len(numbers)

Sphinx 스타일 독스트링

Sphinx는 파이썬 문서를 생성하는 인기 있는 도구입니다. 그 스타일은 reStructuredText 형식과 유사합니다:

def 피보나치(n):
"""
n개의 피보나치 수를 생성합니다.

:param n: 생성할 피보나치 수의 개수
:type n: int
:return: 피보나치 수의 목록
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

독스트링 vs 주석

"독스트링과 일반 주석의 차이는 무엇인가요?"라는 질문을 하실 수 있습니다. 위대한 질문입니다! 그것을 분석해보겠습니다:

1. 문법: 독스트링은 삼중 따옴표를 사용하고, 주석은 #를 사용합니다.
2. 위치: 독스트링은 정의 바로 뒤에 오고, 주석은 어디서나 가능합니다.
3. 목적: 독스트링은 코드가 무엇을 하는지 설명하고, 주석은 그가 어떻게 하는지 설명합니다.
4. 접근성: 독스트링은 프로그래ム적으로 접근할 수 있지만, 주석은 그렇지 않습니다.

빠른 예를 통해 설명하겠습니다:

def 더하기(a, b):
"""
두 숫자를 더하고 결과를 반환합니다.
"""
# 이것은 우리가 덧셈을 수행하는 방법을 설명하는 주석입니다
return a + b  # 이것은 인라인 주석입니다

그리고 이렇게 끝입니다, 여러분! 우리는 파이썬 독스트링의 모든 것을 다루었습니다. 잊지 마세요, 좋은 문서는 미래의 여러분(또는 다른 개발자들)에게 자신의 길을 안내하는 물결의 breadcrumb처럼 된 것입니다. 지금은 좀 더 많은 노력이 필요할 수도 있지만, 나중에는 그것에 감사하게 될 것입니다!

다음은 우리가 다룬 독스트링 스타일의 빠른 참조 표입니다:

스타일	요약	예제
단일 줄	간략한, 한 줄 요약	"""숫자의 제곱을 반환합니다."""
다중 줄	자세한 설명과 파라미터, 반환 값	"""직사각형의 면적을 계산합니다.\n\nParameters:\n..."""
구글	Args, Returns, Raises 섹션 포함	"""두 숫자를 나눕니다.\n\nArgs:\n..."""
NumPy/SciPy	Parameters와 Returns 섹션을 더 자세하게 형식화	"""숫자의 목록의 산수 평균을 계산합니다.\n\nParameters\n----------\n..."""
Sphinx	:param:, :type:, :return:, :rtype: 필드 사용	"""n개의 피보나치 수를 생성합니다.\n\n:param n: ..."""

코딩을 즐겁게 하세요, 그리고 여러분의 독스트링이 항상 명확하고 정보성 있기를!

Credits: Image by storyset