https://www.oreilly.com/library/view/clean-code-in/9781788835831/
[클린코드의 중요성]
- 클린코드는 PEP-8 (Python Enhancemnet Proposal #8, Style Guide for Python Code) 등 코딩 스타일(코드 포매팅) 그 이상을 의미. 품질 좋은 SW를 개발하고, 견고하고 유지 보수가 쉬운 시스템을 만들고, 기술 부채 (후에 bug라는 이자를 만들어 낼)를 회피하는 것을 말함
- 그러나 코드 포매팅 (코딩 가이드라인) 역시 작업 효율화를 위해 중요함
- 프로젝트 코딩 스타일 가이드 준수
- 좋은 코드 레이아웃에서 가장 필요한 특성은 일관성
- 파이썬이 따라야 하는 코딩 스타일은 PEP-8
- PEP-8의 특징 :
- 검색 효율성 : 변수 값 할당 시 띄어쓰기,(location = 1) 키워드 인자 값 할당 시 띄어쓰기 안함 (location=1)
- 일관성 : 코드 레이아웃, 문서화, 이름 작명 규칙 등이 동일
- 코드 품질 : 코드가 구조화 되어 있으면 버그 발견이 용이, 코드 품질 도구나 정적 분석 도구를 사용하면 디버깅에 유리
[Docstring & Annotation]
- 파이썬 코드 안에 직접 문서화하는 법
- 문서화는 주석과 다름. 주석(commnet)는 가급적 피해야만 함
- 파이썬은 동적으로 타입을 결정하므로 함수, 메서드를 거치면 변수나 객체의 타입을 알기 어려움. 어노테이션을 통해 정보를 명시
- 또한 어노테이션 사용시 Mypy 같은 도구를 사용해 타입 힌트 등의 자동화된 검증을 실행 가능
- Docstring :
- 코드에 주석을 다는건 나쁜 습관. 주석이 많다는건 코드가 명확하지 않다는 것. 때론 주석은 냅두고 코드만 업데이트하여 혼란을 초래하기도 함
- 가령 예상되는 함수의 입력과 출력을 문서화 하면 사용자가 사용할 때 함수가 어떻게 동작하는지 쉽게 이해
- 유용하게 사용되려면 여러 줄에 걸쳐 상세하게 작성되어야 함
- 객체에 docstring이 정의되어 있으면 __doc__ 속성을 통해 접근 가능. my_function.__doc__ , 런타임 중 접근 및 수정도 가능
- SW는 단순한 코드가 아님. 코드가 변경 될 경우 Wiki, 매뉴얼, README, Docstring 등 관련된 모든 내용이 업데이트 되는 것이 중요
- Annotation :
- 기본 아이디어 : 코드 사용자에게 함수 인자로 어떤 값이 와야 하는지 힌트를 주자 (Type Hinting)
- 타입 뿐 아니라 변수를 이해하는데 도움이 되는 어떤 형태의 메타 데이터라도 지정 가능
- 하지만 파이썬이 타입을 검사하거나 강제하지는 않음 (어노테이션을 이용해 구현은 가능)
- ->를 활용해 반환 예상 타입도 지정 가능
- 타입뿐 아니라 파이썬 인터프리터에서 유효한 어떤것도 사용 가능. 변수의 의도를 설명하는 문자열 등
- 어노테이션 사용시 __annotation__ 속성이 생겨서 접근 가능
- https://blog.hannal.com/2015/03/keyword-only-arguments_and_annotations_for_python3/#fn:2
- 파이썬 3.6부터는 변수에 값을 지정하지 않는 채로 변수의 타입을 선언 할 수 있음
123class Point:lat: floatlong: float - docstring와 annotation은 보완적인 관계
1234def data_from_response(repose: dict) ->dict:if response["status"] != 200:raise ValueErrorreturn {"data" : response["payload"]}
보다는 docstring을 통한 설명을 통해
123456789101112131415161718def data_from_response(repose: dict) ->dict:'''- response 사전의 예제 ::{"status" : 200, # <int>"playload": {...} #반환하려는 사전 데이터...}- 반환 사전 값의 예제 ::{"data" : { . .} }-발생 가능한 예외:- HTTP status가 200이 아닌 경우 ValueError 발생'''if response["status"] != 200:raise ValueErrorreturn {"data" : response["payload"]}
함수에 대해 더 잘 이해 할 수 있음.
[Tools]
- Pylint : PEP-8을 준수했는지 검사하는 도구. pip install pylint
- Black : 자동 코드 포메팅 (http://github.com/ambv/black)
- Makefile : 리눅스 개발환경 빌드 자동화
- mypy : 정적 타입 검사 도구