들어가며

도서관에 들어온 신착자료 목록을 보다가 <파이썬 클린 코드>를 발견했다. 어렴풋이 필요하다고 느끼고는 있지만, 클린 코드가 정확히 뭘 뜻하는지 몰랐기에 빌려왔다.

막상 내용을 훑어보니 중반 이후는 내가 소화하기 힘든 내용이고, 아직까진 ad-hoc 분석을 위해 python을 쓰는 입장에서 다 필요한 것 같지도 않다. 하지만 현재 기준으로 필요하다 느껴지고 이해할 수 있는 범위 내에서 최대한 흡수해보기로 했다.

우선은 1장 먼저 요약해본다.


서문

  • 이 책은 소프트웨어 공학과 파이썬의 교차점을 찾아, 실제 어떻게 개발해야 하는지를 다룸
  • 클린 코드에 대한 절대적인 기준을 제시하진 않음. 그런 코드는 있을 수 없음.
  • 파이썬이 코드의 가독성과 유지보수성을 높이기 위해 제공하는 기능들을 모두 살펴볼 것임
    • 언어 자체가 제공하는 기능
    • 소프트웨어 공학 기법이 어떻게 적용되는지
  • 이 책은 실용서임. 학습보다는 실제 프로젝트에 사용될만한 것들을 다뤘음
    • 정의, 권장사항을 주의깊게 살펴보고, 실용적 측면에서 이해할 것.
    • 결국엔 실용성이 이상보다 우선이다.


1장. 소개, 코드 포매팅과 도구

  • 파이썬에서 개발환경 설정에 필요한 주요 도구
  • 정적 분석, 문서화, 타입 검사, 코드 포매팅 같은 도구를 사용해 가독성 높은 코드를 작성하기 위한 가이드라인 제시

클린 코드란 무엇인가? WHAT

  • 클린 코드의 정의는 주관적이다.
    • 유일하고 엄격한 정의, 측정할 방법은 없음
    • 기계나 스크립트가 아닌 전문가가 판단할 수 있는 것
    • 우리 자신이 클린코드를 판단할 수 있는 유일한 사람임
  • 클린 코드의 본질은 다른 엔지니어가 코드를 읽고 유지관리할 수 있는지 여부에 달려 있다.
    • 프로그래밍 언어의 용도란 컴퓨터가 아닌 다른 개발자에게 아이디어를 전달하는 것
    • 우리는 코드를 작성하는 것보다 읽는 데 많은 시간을 소비함
  • 클린 코드는 필수적인 것이자, 포매팅 이상의 중요한 것을 의미
    • 이 책을 통해 좋은 코드/나쁜 코드의 차이점을 이해하고, 훌륭한 코드와 아키텍처의 특징을 식별해 자기만의 정의를 하길 바람


클린 코드는 왜 중요한가? WHY

  • 클린 코드가 중요한 이유
    • 유지보수성 향상
    • 기술 부채의 감소
    • 애자일 개발을 통한 효과적 작업 진행
    • 성공적 프로젝트 관리로 이어짐
  • 민첩한 개발과 지속적인 배포 가능
    • 유지보수 가능한 좋은 코드는 필수
    • 목적지에 빨리 가기 위해 일정하고 예측 가능한 속도로 달리고 싶다면, 필수적인 도로사정이 곧 코드의 상태
  • 기술 부채
    • 나쁜 결정이나 적당한 타협의 결과로 생긱 소프트웨어적 결함
    • 부채는 늘어난다. 지금 코드를 바꾸는 것보다 미래에 변경하기가 더 어려움.
    • 기술팀이 코드를 수정하고 리팩토링하기 위해 멈추는 것이 기술부채에 비용을 지불하는 것
    • 장기적이고 근본적인 문제를 포함함. 언젠가 돌발 변수 발생.
    • 코드 품질을 관리하지 않으면 결과적으로 기술 부채가 누적될 가능성이 높음

어떻게 해야 하나? HOW TO

  • 파이썬이 제공하는 기능을 사용해 자체 문서화된 코드를 작성한다.
  • 팀 멤버들이 문제의 본질을 해결하는 데 초점을 맞출 수 있게, 코드 레이아웃을 일정하게 유지하도록 도구를 설정한다.

코드 포매팅이 클린코드인가? (-> 아니다)

  • 클린 코드는 코딩 표준, 포매팅, 린팅도구나 다른 검사도구를 사용한 코드 레이아웃 설정 이상을 말한다.
    • 소프트웨어의 품질
    • 시스템의 유지보수성
    • 기술 부채 회피
  • PEP-8 등의 표준을 100% 준수해도 클린코드의 요건을 충족하지 못할 수 있음
  • 그러나 작업 효율화를 위해 올바른 코드 포매팅은 필요

코딩스타일 가이드 준수

  • 코딩스타일이란?
    • 좋은 코드 레이아웃의 특징은 일관적인 구조
    • 가독성이 높아지고 이해하기 쉬워짐
  • 왜 중요한가?
    • 팀의 모든 멤버가 신속하게 패턴을 파악할 수 있고
    • 오류를 쉽게 감지할 수 있음
  • 어떻게 해야 하나?
    • 파이썬은 특히 PEP-8을 따라야 함
    • 작업의 특수성에 따라 일부만 채택해도 좋지만 다른 표준보다는 PEP-8을 권장
    • 파이썬 구문을 실제로 만든 핵심 개발자가 만들었음

PEP-8의 특징

  • 검색 효율성 (Grepability)
  • 일관성
  • 코드 품질
    • 코드 품질도구를 사용하면 잠재적 버그를 찾을 수 있음
    • 정적 분석도구를 사용해 버그 개수 감소 가능

코딩스타일 자동화하는 방법

Docstring과 어노테이션

  • 파이썬 코드 안에 직접 문서화하는 방법
    • 데이터 타입을 설명
    • 예제 제공
  • 주석은 가급적 피해야 함

1) Docstring

  • 소스 코드에 포함된 문서 (documentation)
  • 코드 내에 배치되는 리터럴 문자열
  • ‘이유’가 아니라 ‘설명’이다. 즉, 코멘트가 아니라 문서다.
  • 주석(comment)을 다는 것은 나쁜 습관임
    • 코드로 아이디어를 제대로 표현하지 못한 것
    • 오해의 소지가 있음(주석과 코드 동작이 다른 경우)
    • 코드 변경 시 주석 업데이트를 깜박하는 경우 발생
    • 필요한 경우 : 외부 라이브러리에 오류가 있을 때
  • Docstring은 코드의 특정 컴포넌트(모듈, 클래스, 메서드, 함수)에 대한 문서화
    • 가능한 많이 추가하는 것이 좋음
    • 파이썬의 동적 타이핑 : 파라미터의 값을 체크하거나 강요하지 않음
    • 예상되는 함수의 입력과 출력을 문서화하면 사용자가 이해하기 쉬움
  • 단점
    • 지속적인 수작업 필요
    • 여러 줄로 상세히 작성해야 유용함
  • 그러나 문서화에는 결국 수작업이 필요함
    • 자동 생성된 문서는 유용성 낮음
    • 가치 있는 문서에 팀원 노력 필요
    • 코드를 변경한 경우 위키, 매뉴얼, Readme 파일, docstring등 모든 내용 업데이트 필요

2) 어노테이션

  • 코드 사용자에게 함수 인자로 어떤 값이 와야 하는지 힌트를 주는 것
  • 어노테이션은 타입 힌팅(type hinting)을 활성화함
  • 어노테이션을 통해 할 수 있는 것
    • 변수의 예상 타입을 지정
    • 함수 반환 값에 대한 예상 타입을 지정
    • 파이썬 인터프리터에서 유효한 것들(변수의 의도를 설명하는 문자열, 콜백, 유효성 검사 함수로 사용할 수 있는 callable 등)
  • 타입 힌팅
    • 인터프리터와 독립된 추가도구를 사용해 올바른 타입이 사용됐는지 확인
    • 호환되지 않는 타입 발견 시 사용자에게 힌트 주는 것
    • Mypy
    • 테스트나 검사 시 바로 버그찾을 수 있음. 다른 정적 분석도구와 함께 사용.
  • 최근 변경사항
    • 파이썬 3.6부터 함수 파라미터와 리턴뿐 아니라 변수에 직접 주석을 달 수 있음
    • PEP-526에서 소개

어노테이션은 docstring을 대체하는가?

  • 둘은 서로 보완적인 개념이므로 둘 다 필요하다.
  • docstring에 포함된 정보 일부를 어노테이션으로 옮길 수 있음
  • 그러나 더 나은 문서화를 위해 docstring 필요
    • 동적 데이터 타입과 중첩 데이터 타입의 경우
    • 예상 데이터 예제 제공
    • 입력값과 반환값의 예상되는 형태를 이해할 수 있음

기본 품질 향상을 위한 도구 설정

  • Mypy를 사용한 타입 힌팅
    • 가장 일반적으로 사용하는 정적 타입검사 도구
    • 버그를 조기에 발견 가능하지만 잘못 탐지하기도 함
    • 프로젝트 셋업 파일에 종속성을 추가하는 것이 좋음
    • 잘못 탐지하는 경우 무시하도록 설정 가능 
      type_to_ignore = "something" # type: ignore
  • Pylint를 사용한 코드 검사
    • 가장 완결성 높고 설정가능한 옵션 많음
    • .pylintrc 파일을 통해 설정값 변경 가능
  • 자동 검사 설정 : makefile
    • 빌드 자동화하는 일반적 도구
    • 포매팅 검사, 코딩 컨벤션 검사 자동화에 사용할 수 있음
  • 자동 검사 설정 : Black
    • 팀에서 사용하는 컨벤션, 코드 구조화를 위한 자동화
    • 자동으로 코드 포매팅함

마무리하며 (4.9 업데이트)

  • 이 책의 정리는 현재 시점에서 일시 중지하기로 한다.
  • 2~3장을 읽어본 결과, 지금 내 수준에는 전혀 맞지 않는다는 결론을 내렸다.
    • 파이썬을 갓 시작한 초심자가 읽기엔 고급 내용이다.
    • 나는 파이썬을 데이터 분석/핸들링 목적으로 쓰는데, 이 책은 소프트웨어 공학 관점에서 파이썬의 메서드, 객체, 클래스 등을 다룬다.
  • 내가 필요로 했던 건, 이 책처럼 유지보수와 효율적인 재활용의 관점에서 ‘데이터 분석’에 쓰이는 코드와 노하우를 다룬 책이다. 실무자가 쓴 그런 파이썬 책이 시중에 나와 있는지는 리서치를 좀 해봐야 할 듯 하다.
  • 나중에 언젠가 데이터 프로덕트를 만들게 되면 이 책을 참고하게 될 지도 모르겠다.