Chapter1. Code formatting and Tools

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부터는 변수에 값을 지정하지 않는 채로 변수의 타입을 선언 할 수 있음
    
    Python

    class Point: lat: float long: float

    1 2 3

    class Point:     lat: float     long: float

  • docstring와 annotation은 보완적인 관계
    
    Python

    def data_from_response(repose: dict) ->dict: if response["status"] != 200: raise ValueError return {"data" : response["payload"]}

    1 2 3 4

    def data_from_response(repose: dict) ->dict: if response["status"] != 200: raise ValueError return {"data" : response["payload"]}

    
    보다는 docstring을 통한 설명을 통해
    
    Python

    def data_from_response(repose: dict) ->dict: ''' - response 사전의 예제 :: { "status" : 200, # <int> "playload": {...} #반환하려는 사전 데이터 ... } - 반환 사전 값의 예제 :: {"data" : { . .} } -발생 가능한 예외: - HTTP status가 200이 아닌 경우 ValueError 발생 ''' if response["status"] != 200: raise ValueError return {"data" : response["payload"]}

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

    def data_from_response(repose: dict) ->dict: ''' - response 사전의 예제 :: {    "status" : 200, # <int>            "playload": {...} #반환하려는 사전 데이터   ... } - 반환 사전 값의 예제 :: {"data" : { . .} }         -발생 가능한 예외:         - HTTP status가 200이 아닌 경우 ValueError 발생 ''' if response["status"] != 200: raise ValueError return {"data" : response["payload"]}

    
    함수에 대해 더 잘 이해 할 수 있음.

[Tools]

• Pylint : PEP-8을 준수했는지 검사하는 도구. pip install pylint
• Black : 자동 코드 포메팅 (http://github.com/ambv/black)
• Makefile : 리눅스 개발환경 빌드 자동화
• mypy : 정적 타입 검사 도구