파이썬 클린 코드 – 1
소개, 코드 포매팅과 도구
Docstring과 어노테이션
Docstring
- 주석을 피하고 docstring을 이용하자
|
1 2 3 4 5 6 7 8 9 10 |
def my_function(): """This function returns None. Returns: None """ return None help(my_function) print(my_function.__doc__) |
- Pycharm의 settings에서 docstring을 검색하면 유용한 옵션들이 있다.
- Autodoc을 이용하면 자동으로 문서화를 해준다.
어노테이션
- 함수의 인자와 리턴 타입의 대한 정보를 사용자에게 줄 수 있다.
- 하지만 강제되는 것은 아니고 단지 힌트일 뿐이다.
|
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 |
class Point: """GPS position. """ lat: float long: float def __init__(self, lat, long): self.lat = lat self.long = long def locate(latitude: float, longitude: float) -> Point: """Create GPS Point instance. Args: latitude: The latitude of GPS position. longitude: The longitude of GSS position. Returns: Point. """ return Point(latitude, longitude) print(Point.__annotations__) # {&#039;lat&#039;: <class &#039;float&#039;>, &#039;long&#039;: <class &#039;float&#039;>, &#039;abc&#039;: <class &#039;float&#039;>} print(locate.__annotations__) # {&#039;latitude&#039;: <class &#039;float&#039;>, &#039;longitude&#039;: <class &#039;float&#039;>, &#039;return&#039;: <class &#039;__main__.Point&#039;>} |
어노테이션은 docstring을 대체하는 것일까?
- docstring과 어노테이션은 상호 보완적이다.
|
1 2 3 4 5 6 |
def data_from_response(response: dict) -> dict: if response["status"] != 200: raise ValueError return {"data": response["payload"]} |
- 이러한 함수라면 어노테이션 만으로는 기대되는 response 객체의 형태나 결과 값의 형태를 파악할 수가 없다.
- docstring을 이용하면 좀 더 상세한 문서화가 가능하다.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
def data_from_response(response: dict) -> dict: """If There is no problem in response, return payload of response. - The example of response dict:: { "status": 200, # <int> "timestamp": "....", # String of current time in ISO format "payload": { ... } # To return dict. } - The example of return:: {"data": { ..} } - Raisable exception:: - If HTTP status is not 200, raise ValueError. """ if response["status"] != 200: raise ValueError return {"data": response["payload"]} |
기본 품질 향상을 위한 도구 설정
- 동료가 작성 코드를 리뷰할 때,
- 이 코드를 동료 개발자가 쉽게 이해하고 따라갈 수 있을까?
- 업무 도메인에 대해서 말하고 있는가?
- 팀에 새로 합류하는 사람도 쉽게 이해하고 효과적으로 작업할 수 있을까?
-
모든 검사는 자동화 해야 한다.
-
Mypy : 정적 타입 검사 도구
-
Pylint : PEP-8 준수 검사