728x90
파이썬에서 유명한 라이브러리 코드를 보게 되면 무언가 많이 작성되어 있는 것을 볼 수가 있다.
def generate_identified_filename(filename: Path, identifier: str) -> Path:
"""
Append a string-identifier at the end (before the extension, if any) to the provided filepath
Args:
filename: pathlib.Path The actual path object we would like to add an identifier suffix
identifier: The suffix to add
Returns: String with concatenated identifier at the end of the filename
"""
return filename.parent.joinpath(filename.stem + identifier).with_suffix(filename.suffix)* transformers 의 코드 중 하나
이런 식으로 함수 아래에 """ 따옴표를 이용하여 무언가가 많이 적혀 있는데 이것을 Docstring이라고 하는데 이것에 대해 알아보려고 한다.
Docstring이란?
쉽게 말해서 소스 코드에 포함된 문서라고 말할 수 있다. docstring은 문자열이며, fucntion logic을 문서화하기 위해 작성한다. Docstring은 주석과는 다르게 Python의 첫 번째 실행 가능한 문장으로 작성되며, Python 인터프리터에 의해 처리되어 해당 객체의 __doc__ 특수 속성에 저장됩니다. 이를 통해 프로그램 실행 중에도 해당 정보에 접근할 수 있다.
Docstring 작성 방법
- 함수 정의와 타입 힌트 적용: 함수 정의에서 매개변수와 반환 값에 타입 힌트를 적용
- 문자열 시작: 함수 정의 바로 아래에 삼중 따옴표 (""")를 사용해 docstring을 시작
- 요약 설명: 함수가 수행하는 작업에 대한 간결하고 명확한 한 줄 요약을 포함
- 상세 설명 (선택 사항): 요약 설명 다음에 빈 줄을 두고 필요한 경우 함수의 동작을 보다 상세히 설명
- 매개변수 설명: Parameters 섹션에서 각 매개변수의 이름, 타입, 그리고 설명을 제공
- 반환 값 설명: Returns 섹션에서 함수가 반환하는 값의 타입과 그 의미를 설명
- 예외 설명: Raises 섹션에서 함수 실행 중 발생할 수 있는 예외와 그 상황을 나열하고 설명
- 예시 설명: Examples 섹션에서 함수의 실행 예시와 결과 값에 대해 나열하고 설명
타입 힌트 작성
타입 힌트는 typing 모듈과 pydantic 모듈을 사용합니다. typing은 3.5 버전부터 일반적으로 사용하고 3.10 버전부터는 pydantic 모듈을 사용한다. 특히 pydantic은 FastAPI와 같은 API에서 많이 사용하고 그 외에는 거의 typing 모듈을 사용한다고 보면 된다.
예시
typing 모듈을 사용하지 않았을 때
def add(a: int, b: int) -> int:
"""
두 정수의 합을 계산하여 반환합니다.
Parameters:
a (int): 첫 번째 정수. 정수가 아닐 경우 TypeError 발생.
b (int): 두 번째 정수. 정수가 아닐 경우 TypeError 발생.
Returns:
int: 두 수의 합
Raises:
TypeError: `a` 또는 `b`가 정수가 아닐 때 발생
Examples:
>>> add(10, 20)
30
>>> add("ten", 20)
TypeError: Both arguments must be integers
"""
if not isinstance(a, int) or not isinstance(b, int):
raise TypeError("Both arguments must be integers")
return a + b
typing 모듈을 사용했을 때
from typing import Union
def add_numbers(x: Union[int, float], y: Union[int, float]) -> float:
"""
두 숫자의 합을 계산하여 반환합니다.
Parameters:
x (Union[int, float]): 첫 번째 숫자. 정수 또는 부동소수점 수가 될 수 있습니다.
y (Union[int, float]): 두 번째 숫자. 정수 또는 부동소수점 수가 될 수 있습니다.
Returns:
float: `x`와 `y`의 합.
Examples:
>>> add_numbers(1, 2)
3
>>> add_numbers(1.5, 2.3)
3.8
Notes:
이 함수는 `int` 또는 `float` 타입의 두 입력값을 받아 그 합을 `float`로 반환합니다.
"""
return x + y
'Coding > Clean Code' 카테고리의 다른 글
| [PEP] Pythonic한 Name Convention에 대해 알아보자 (1) | 2024.06.10 |
|---|---|
| [Clean Code] 프로그래밍 명명 규칙인 Camel Case, Snake Case, Pascal Case, Kebab Case에 대해 알아보자 (0) | 2024.06.09 |
