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부터는 변수에 값을 지정하지 않는 채로 변수의 타입을 선언 할 수 있음
    • docstring와 annotation은 보완적인 관계

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

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

[Tools]

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