Docstring#
python에서 함수, 클래스, 모듈에 대한 문서화를 위해 사용되는 문자열.
이는 코드의 가독성을 높이고 다른 개발자들이 코드를 이해하는 데 도움을 준다.
주요 특징#
- 큰따옴표 세 개(""") 또는 작은따옴표 세 개(’’’)로 둘러싸인 문자열이다.
- 함수, 클래스, 모듈의 첫 번째 문장으로 위치한다.
__doc__ 속성을 통해 프로그램 실행 중에 접근할 수 있다.- 내장 함수
help()를 통해 문서를 볼 수 있다.
- 코드의 목적과 동작을 설명한다.
- 함수의 매개변수, 반환값, 예외 등을 문서화한다.
- 모듈이나 클래스의 전반적인 기능을 설명한다.
- 자동 문서 생성 도구(예: Sphinx)를 통해 API 문서를 생성할 수 있다.
고려해야 할 중요한 점들#
- 일관성: 프로젝트 전체에서 동일한 스타일을 사용해야 한다.
- 명확성: 설명은 간단하고 명확해야 하며, 예시가 있으면 더 좋다.
- 완전성: 모든 매개변수, 반환값, 예외 상황을 문서화해야 한다.
- 최신성: 코드가 변경될 때 Docstring도 함께 업데이트해야 한다.
활용 방법#
1
2
3
4
5
6
| # Docstring 확인하기
help(google_style) # help() 함수 사용
print(google_style.__doc__) # __doc__ 속성 직접 접근
# 대화형 셸에서 사용
>>> google_style? # IPython/Jupyter에서
|
자동 문서 생성을 위한 도구들#
- Sphinx: Python 프로젝트의 표준 문서화 도구.
- pdoc: 간단한 API 문서를 자동으로 생성한다.
- MkDocs: Markdown 기반의 문서 생성 도구이다.
각 스타일은 프로젝트의 성격이나 팀의 선호도에 따라 선택할 수 있다.
중요한 것은 프로젝트 내에서 일관성 있게 사용하는 것.
또한, IDE나 문서 생성 도구와의 호환성을 고려하여 선택하는 것이 좋다.
Docstring 포맷#
주요 Docstring 포맷에는 Google 스타일, reStructuredText(Sphinx) 스타일, NumPy 스타일이 있다.
Google 스타일#
특징:
- 가장 읽기 쉽고 직관적인 포맷.
- 특별한 도구 없이도 이해하기 쉽다.
- 많은 개발자들이 선호하며 널리 사용된다.
- Args, Returns, Raises 등의 섹션을 명확하게 구분한다.
예시:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| def google_style(param1: str, param2: int) -> dict:
"""Google 스타일의 docstring 예시입니다.
이 함수는 Google 스타일의 문서화 방식을 보여줍니다.
여러 줄의 설명을 작성할 수 있습니다.
Args:
param1: 첫 번째 매개변수에 대한 설명
param2: 두 번째 매개변수에 대한 설명
Returns:
결과를 담은 사전을 반환합니다.
Raises:
ValueError: 잘못된 입력이 주어질 경우
Examples:
>>> google_style("test", 123)
{'test': 123}
"""
if not isinstance(param2, int):
raise ValueError("param2 must be an integer")
return {param1: param2}
|
reStructuredText(Sphinx) 스타일#
특징:
- Python 공식 문서에서 사용되는 형식
- Sphinx 문서 생성 도구와 가장 잘 호환된다.
- 매우 상세한 문서화가 가능하다.
- 다양한 지시어(directive)를 사용할 수 있다.
- 문법이 다소 복잡할 수 있다.
예시:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| def sphinx_style(param1: str, param2: int) -> dict:
"""
Sphinx 스타일의 docstring 예시입니다.
:param param1: 첫 번째 매개변수에 대한 설명
:type param1: str
:param param2: 두 번째 매개변수에 대한 설명
:type param2: int
:returns: 결과를 담은 사전
:rtype: dict
:raises ValueError: 잘못된 입력이 주어질 경우
.. note::
이것은 부가적인 노트입니다.
.. warning::
이것은 경고 메시지입니다.
"""
if not isinstance(param2, int):
raise ValueError("param2 must be an integer")
return {param1: param2}
|
NumPy 스타일#
특징:
- 과학 계산 커뮤니티에서 널리 사용된다.
- 매개변수와 반환값을 명확하게 구조화한다.
- 수학적 표현이나 복잡한 매개변수를 설명하기에 적합하다.
- Google 스타일보다 더 형식적인 구조를 가진다.
예시:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
| def numpy_style(param1: str, param2: int) -> dict:
"""
NumPy 스타일의 docstring 예시입니다.
이 함수는 NumPy 스타일의 문서화 방식을 보여줍니다.
Parameters
----------
param1 : str
첫 번째 매개변수에 대한 설명
param2 : int
두 번째 매개변수에 대한 설명
Returns
-------
dict
결과를 담은 사전
Raises
------
ValueError
잘못된 입력이 주어질 경우
See Also
--------
google_style : 관련된 함수에 대한 참조
sphinx_style : 다른 관련 함수에 대한 참조
Notes
-----
추가적인 노트를 작성할 수 있습니다.
수식도 포함할 수 있습니다.
Examples
--------
>>> numpy_style("test", 123)
{'test': 123}
"""
if not isinstance(param2, int):
raise ValueError("param2 must be an integer")
return {param1: param2}
|
클래스 Docstring 예시#
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
| class ExampleClass:
"""예시 클래스입니다.
이 클래스는 다양한 docstring 스타일을 보여주기 위한 예시입니다.
Attributes:
attr1 (str): 첫 번째 속성에 대한 설명
attr2 (int): 두 번째 속성에 대한 설명
"""
def __init__(self, attr1: str, attr2: int):
"""
클래스 생성자입니다.
Args:
attr1: 첫 번째 속성값
attr2: 두 번째 속성값
"""
self.attr1 = attr1
self.attr2 = attr2
@property
def combined(self) -> str:
"""속성 값들을 결합합니다.
Returns:
str: 결합된 문자열
"""
return f"{self.attr1}{self.attr2}"
|
참고 및 출처#