파이썬 코드안에 직접 문서화 하는 방법을 정리한다.
여기서 문서화라고 하는 것은 코드에 주석을 추가하는 것과는 다르다.
코드에는 가능한 적은 주석을 갖는 것을 목표로 해야 한다. 좋은 코드는 코드 자체가 문서화되어 있기 때문이다.
주석이 아닌 의미 있는 함수나 객체, 변수명을 사용하는 것과 같은 방법으로 말이다.
그렇다면 파이썬에서 주석이 아닌 코드 문서화는 어떻게 할 수 있을까?
바로 docstring, annotation을 통해서다.
docstring
docstring은 소스 코드에 포함된 문서이다. 이것은 기본적으로 리터럴 문자열이며 문서이다. 이유가 아닌 설명이다.
docstring은 모듈, 클래스, 메서드 또는 함수에 대해 문서를 제공한다. 전체적인 관점에서 해당 컴포넌트가 어떻게 설계되었는지 힌트를 줄 수 있기 때문에 중요한 모듈, 함수 및 클래스에는 docstring을 추가하는 것이 좋다. 또한, 파이썬은 동적 타입 언어이기 때문에 파라미터와 리턴 값의 데이터 타입의 설명으로도 활용할 수 있다.
사용 방법은 간단하다.
# 코드에 대한 설명으로 사용
def my_function():
"""임의의 계산 수행"""
return None
# 파라미터, 리턴 타입, 함수의 역할을 설명하는데 사용
# 출처 : https://www.datacamp.com/tutorial/docstrings-python
def string_reverse(str1):
#Returns the reversed String.
#Parameters:
# str1 (str):The string which is to be reversed.
#Returns:
# reverse(str1):The string which gets reversed.
reverse_str1 = ''
i = len(str1)
while i > 0:
reverse_str1 += str1[i - 1]
i = i- 1
return reverse_str1
annotation
annotation의 기본적인 아이디어는 코드 사용자에게 함수 인자로 어떤 값이 와야 하는지 힌트를 제공한다.
말 그대로 힌트이기 때문에 강제성은 존재하지 않고 함수 사용자에게 타입에 대한 유용한 정보를 제공할 수 있다.
사용 방법을 보자.
from dataclasses import dataclass
# 클래스 속성 타입 정의로 사용
@dataclass
class Point:
lat: float
long: float
# 함수 파라미터, 리턴 타입으로 사용
def locate(latitude: float, longitude: float) -> Point:
"""맵에서 좌표에 해당하는 객체를 검색"""
return Point(latitude, longitude)
if __name__ == "__main__":
print(locate(1.1, 2.2))
# 타입을 강제하지 않기 때문에 에러가 발생하지 않음.
print(locate("1.1", "2.2"))
파이썬은 동적 언어이기 때문에 모든 함수나 클래스에 어노테이션을 사용해야 하는 것은 아니다. 하지만 타입을 확인하는 것이 중요한 경우에는 사용하면 효과적일 것이고, 타입을 잘못 사용해서 발생하는 잠재적인 버그는 mypy, pytype 같은 일종의 린터 도구를 같이 사용하면 쉽게 찾을 수 있을 것이다.
annotation은 docstring이 표현할 수 있는 타입에 대한 힌트 기능을 갖기 때문에 docstring은 안 써도 되지 않을까라는 의문이 생길 수도 있다. 하지만, docstring은 annotation이 표현할 수 없는 설계나 기능에 대한 설명을 포함할 수 있기 때문에 보완적인 개념이며, 각각 필요시 적절히 사용하면 된다.
출처
- 파이썬 클린 코드