gitlin-i

gitlin-i

Python Clean Code

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

1-1.클린 코드의 정의

클린 코드에 대한 유일하고 엄격한 정의는 없다.
프로그래밍 언어는 아이디어를
:man: :arrow_right: :computer: 로 전달하는 것도 맞지만,
핵심은 :man: :left_right_arrow: :man: 아이디어를 다른 개발자에게 전달하는 것이다. 이것이 클린코드의 본질이다.

즉, 클린코드인지 아닌지는 다른 엔지니어가 코드를 읽고 유지관리할 수 있는지 여부에 달려있다.

1-2. 프로젝트 코딩 스타일 가이드 준수

좋은 코드 레이아웃에서 가장 필요한 특성은 일관성이다. 코드가 일관되게 구조화되어 있으면 가독성이 높아지고 이해하기 쉬워진다.
만약 팀원 모두가 코드의 일관성을 유지하지 않고 자신의 방식으로 일을 하고 있다면, 결국은 많은 시간과 노력을 투입해야만 할 것이다.

특히, 파이썬이 따라야 하는 코딩 스타일은 PEP-8이다

(PEP: Python Enhancement Proposal의 약자.파이썬 개선을 위한 제안서. PEP-8은 8번째 제안서)
코드를 올바르게 포매팅하는 것은 작업을 효율화하기 위해 중요하지만, 이런 스타일을 100% 준수하더라도 여전히 클린코드의 요건을 충족하지 못할 수 있다.
1-1의 핵심을 기억하자.

다른 표준을 고안하기 보다는 순수 PEP-8을 사용하든 PEP-8을 확장해서 사용할 것을 권장한다.

그 이유는 PEP-8은 이미 파이썬 구문의 많은 특수성을 고려하여 작성되었으며, 이만큼 좋은 표준을 찾기 어렵기 때문이다.

PEP-8 특징

1.검색 효율성
PEP-8은 키워드 인자에 값을 할당할 때는 띄어쓰기를 사용하지 않지만, 변수에 값을 할당할 때는 띄어쓰기를 권고하고 있다.

$grep -nr "location="
./core.py:13: location=current_location,

파라미터 값을 할당하는 곳을 찾음.

$grep -nr "location ="
./core.py:10: current_location = get_location()

변수에 값을 할당하는 곳을 찾음.

2.일관성

코드가 일정한 포맷을 가지면 훨씬 쉽게 읽을 수 있다.

3.코드 품질

코드를 구조화하여 살펴보면 한눈에 코드를 이해하고 버그와 실수를 찾을 수 있다.

1-3.Docstring 어노테이션

코드를 문서화하는 것 != 주석을 추가하는것

주석(Comment)은 가급적 피해야만 한다. 문서화를 통해 데이터 타입이 무엇인지 설명하고 예제를 제공할 수 있다.

Docstring

소스코드에 포함된 문서(Documentation)
Docstring은 Comment가 아닌 Documentation이다.
코드의 특정 컴포넌트(모듈,클래스,메서드 또는 함수)에 대한 문서화

  • 코드에 주석(Comment)을 다는 것은 나쁜습관이다.
    1. 코드로 아이디어를 제대로 표현하지 못했음을 의미
    2. 오해의 소지가 있음.
      사람들이 코드를 변경하고, 주석 업데이트를 까먹는 경우.
      주석의 내용과 코드의 실제 동작이 차이가 나는 경우.

Docstring을 코드에 포함시키는 것이 좋은 이유는 파이썬이 동적 타이핑을 하기 때문이다.
파이썬은 파라미터의 타입을 체크하거나 강요하지 않는다.
:arrow_right: 코드 수정시 어떤 타입을 사용하는지 확인하기 전까지는 알 수 없음.

이런 경우 Docstirng이 도움이 된다

Docstring의 단점

  • 모든 문서화가 그렇듯이 지속적으로 수작업으로 문서를 갱신해야한다. 소프트웨어 엔지니어링에서 피할 수 없는 과제.

Annotation

코드 사용자에게 함수 인자로 어떤 값이 와야하는지 힌트를 주는 것

def locate(latitude: float, longitude: float) -> Point:

latitude, longitude는 float 타입의 변수 Point라는 사용자 정의 클래스의 인스턴스가 반환 물론, 파이썬이 타입을 검사하거나 강제하지는 않는다.

어노테이션을 사용하면 __annotations__ 이라는 특수한 속성이 생긴다.

>>> locate.__annotations__
{'latitude': float, 'longitude': float, 'return':__main__.Point}

어노테이션의 이름과 값을 매핑한 사전타입의 값. 이 정보를 사용하여 문서 생성, 유효성 검증 또는 타입 체크를 할 수 있다.

PEP-484의 발췌 내용

파이썬은 여전히 동적인 타입의 언어로 남을 것이다. 타입힌트를 필수로 하자거나 심지어 관습으로 하자는 것은 아니다.

파이썬 3.6 이상부터 함수 파라미터와 리턴 타입, 변수에 직접 주석을 달 수 있다.

class Point:
    lat: float
    long: float

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

반복적인 확인 작업을 줄이기 위해 코드 검사를 자동 실행하는 기본도구를 권장 CI(지속적인 통합)와 하나가 되어야한다.

  • Mypy 정적 타입 검사 도구
  • Pylint 코드 구조 검사 도구
  • Makefile 자동 검사 도구 (CI 관련), 리눅스 개발환경

코딩 가이드라인 검사-> 올바른 타입 검사-> 테스트 실행

  • Black 자동으로 코드 포매팅 도구. 매우 엄격한 방식으로, 항상 같은 결과를 출력.

이런 도구를 사용하는 것은 절대적인 것은 아님.

참고