[파이썬 클린코드] Chapter1 : 코드 포맷팅과 도구

 

http://www.yes24.com/Product/Goods/114667254

파이썬 클린코드 2nd edition 을 읽고 정리한 내용입니다.

---

들어가며

클린코드란?

다른 사람이 읽고 이해 및 활용(유지보수)할 수 있는 코드를 말한다. 

 

문서화 Documentation

코드를 문서화하는 것은 주석을 추가하는 것과는 다르다는 사실을 인지하기. 코드를 문서화하기 위해서는 docstring과 annotation을 이용할 수 있다. 

코드 주석 code comments

좋은 코드의 경우 이미 명환하게 되어 있기 때문에 주석이 필요하지 않으므로, 최대한 적은 주석을 목표로 하는 것이 좋다. 그렇기 때문에 주석을 작성하기 전에 1.새로운 함수를 추가 하거나 2.다른 더 나은 변수명을 사용 하는 방법으로 개선을 시도해보는 것이 좋다. 

Docstring

소스코드에 포함된 문서를 말할 수 있으며, 코멘트가 아닌 문서라는 점에 유의해야한다. 내가 작성한 docstring을 보고 다른 개발자가 동작방식 혹은 입출력 정보 등을 확인할 수 있어야하므로 주석과는 반대로 최대한 docstring을 추가하려고 하는 것은 좋은 습관이라고 할 수 있다. 이런 문서화를 통해서 함수의 입출력 정보가 어떻게 동작해야하는지 이해할 수 있게 된다. 

코드에 docstring이 정의된 경우 다움과 같은 속성을 이용하여 확인할 수 있다.

# 1.
my_function.__doc__
# 2. 
help(my_function)

doctstring의 단점으로는, 코드가 변경되었을 경우 수동으로 업데이트를 해줘야 한다는 것이다. 그렇기 때문에 간단한 코드의 경우에는 중복된 의미를 가진 docstring은 작성하지 않는 편이 더 나을 수 있다. 

Annotation

Annotation을 이용하면 변수의 예상 타입과 같이 메타데이터들을 지정할 수 있게 된다. lat과 long이 float이라고 예상되는 경우 이렇게 설정할 수 있는데, 타입에 대해 검사하지는 않는다. 

@dataclass:
class Point:
	lat : float
    long : float
   
def locate(latitude : float, longitude : float) -> Point:
	"""맵에서 좌표에 해당하는 객체를 검색"""

또한 Annotation을 이용하면 더 표현력있는 코드를 작성할 수 있게 되는데, 밑에와 같이 어떻게 입력을 해야하는지 더 명확하게 전달할 수 있게 된다. 또한 다른 객체나 클래스로 변경되는 경우에도 기존 Annotation을 그대로 사용하면 된다. 

# Before
def launch_task(delay_in_seconds):
	pass
    
# After
Seconds = float
def launch_task(delay : Seconds):
	pass

 Annotation을 생성 시 __annotations__라는 속성이 생기게 되는데, 이를 통해 문서 생성, 유효성 검증, 타입 체크 등을 할 수 있다.

그리고 Annotation을 생성하게 되면, 보다 쉽고 간결하게 클래스 작성이 가능하다.  __init__에서 변수 선언 후 할당하는 작업을 하지 않아도 된다. 

# Before
calss Point :
	def __init__(self, lat, long):
    		self.lat = lat
        	self.long = long
        
# After
from dataclasses import dataclass
@dataclass
class Point:
	lat : float	
    long : float

• Annotation과 Docstring은 서로 보완적인 개념이라는 것을 인지하자

 

도구설정

동료가 작성한 코드를 살펴볼 때 해야 할 질문

• 이 코드를 동료 개발자가 쉽게 이해하고 따라갈 수 있을까?
• 업무 도메인에 대해서 말하고 있는가?
• 팀에 새로 합류하는 사람도 쉽게 이해하고 효과적으로 작업할 수 있을까?

데이터타입 일관성 검사

여러 도구들이 있지만, 여기서는 mypy와 pytype를 활용할 수 있다. 단, pytype의 경우에는 일시적으로는 다른 유형의 데이터타입을 활용하더라도 결과가 선언된 유형을 준수한다면 오류로 보고하지 않는다. 이러한 도구들이 제대로 검사를 수행하려면, Annotation을 정확하게 작성해야 한다. 

# 기본
mypy 파일명

# 특정 라인에 대한 검사를 무시하게 하는 경우
type_to_ignore = "sth" # type : ignore

일반적인 코드 검증

보다 일반적인 유형의 검사를 위해서는 pylint를 또는 Coala 이용할 수 있다. pylint는 엄격한 수준으로 코드 품질에 대한 검사가 가능하다. Coala의 경우에는 파이썬 뿐 아니라 다른 유형의 언어도 지원한다. 이러한 것으로도 검출되지 않는 경우, 직접 검사가 필요한 사항에 대해 추가할 수 있으므로 이런 방법을 활용해도 좋다. 

자동포매팅

자동으로 코드 형식을 지정하게 하는 것도 유용한 방법 중 하나다. black을 이용하면 항상 같은 형태의 포맷을 가지게 할 수 있다. --check 기능을 활용하면 검사만하고 실제 수정은 하지 않을 수도 있다. 또는 yapf를 이용해서 원하는 범위에만 포매팅을 적용할 수도 있다. 

자동 검사 설정

프로젝트를 컴파일하고 실행하기 위한 설정을 도와주는 도구인 Makefile을 이용해서 자동화를 할 수 있다. 

 

---

혼자서 작성한 코드를 혼자서만 활용하고 있는데, 너무 마구잡이로 코드를 짠 건 아닌가 하는 생각이 들어서 파이썬클린코드를 보기로 했다. 마침 개정판이 나왔길래 개정판으로...! 개념을 훑은 다음에 적용해서 수정할 수 있는 부분은 수정하는 식으로 진행해보려고 한다.