파이썬 클린 코드 (1/10)

1장.  코드 포맷팅과 도구

클린 코드의 중요성

코드의 품질을 관리하지 않는다면 결과적으로 기술 부채가 누적되어 실패한 프로젝트가 될 가능성이 높아진다.

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

 

개인적으로 상당히 공감하는 말이다.

 

클린 코드 판단은 내 코드 리뷰에서도 이루어지는데, 내 코드가 꼼꼼하지 않게 승인돼도 큰 상관이 없다.
리뷰를 받는 코드의 maintainer는 나 자신(=코드 작성자)이기 때문이다.

 

하지만 대부분의 개발자는 은퇴할 때까지 한 곳에서만 일하지 않기 때문에, 내가 이직을 한다면 내 동료는 내가 작성한 코드를 유지보수해야만 한다.

 

내가 팀을 떠날 때의 maintainer는 내 동료이며, 내 코드에 대한 평가는 이때에도 이루어진다.

 

클린 코드를 위해서는 내가 알아볼 수 있는 코드가 아니라 동료도 알아볼 수 있는 코드를 작성해야 한다.

 

 

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

 

이 부분은 개인적으로 팀원 모두 노력이 필요하다고 생각한다.

 

우리는 유틸리티성 모듈의 이름을 정할 때 common, shared, 혹은 utilities라고 정할 수 있다.

 

하지만 공통 모듈임에도 불구하고 만약 여러 동료가 각기 다른 이름으로 모듈을 생성/관리한다면, 그 모듈은 책에서 말하듯이 이해하기 어렵거나 애매한 모듈이 돼버린다.

 

개인적인 생각으로는 비슷한 일이 발생할 때는 팀원에게 의견을 구하고, 프로젝트 내 일관성을 유지하기 위해 의견을 통일해야 하지 않을까 싶다.

 

---

Docstring과 어노테이션

코드에 주석(Comment)을 다는 것은 여러 가지 이유로 나쁜 습관이다. 첫째, 주석은 코드로 아이디어를 제대로 표현하지 못했음을 나타내는 것이다. 만약 무언가를 왜 어떻게 하는지 꼭 설명해야 한다면 그 코드는 아마도 충분히 좋지 못한 것이다. 둘째,

..(중략)..

그러나 docstring의 경우는 좀 다르다. 다시 말하지만 주석을 다는 것이 아니라 코드의 특정 컴포넌트(모듈, 클래스, 메서드 또는 함수)에 대한 문서화이다. 이런 컴포넌트에 사용하는 것은 허용될 뿐 아니라 권장되는 부분이다. 가능한 많은 docstring을 추가하는 것이 좋다.

 

주석(Comment)과 docstring의 차이를 이해하는 것이 중요하다.

 

특히 파이썬은 동적으로 타입을 결정하기 때문에 함수나 메서드를 거치면 변수나 객체의 값이 무엇인지 알기가 어려운 경우가 많다.

 

따라서 docstring을 통해 해당 컴포넌트에 대한 설명이 필요하다.

 

 

... 코드를 변경한 경우 위키(wiki), 사용자 매뉴얼, README 파일 또는 docstring 등 관련된 모든 내용을 업데이트하는 것이 중요하다.

 

.. 고 하지만 막상 실제로 업무를 진행하다 보면 다 챙기는 것은 불가능에 가까운 것 같다. 😢

 

 

동료가 작성한 코드를 살펴볼 때는 다음 질문을 해야 한다.

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

 

나는 습관적으로 위와 같은 고민을 한다.

 

이런 고민 자체가 습관이 되다 보니 비록 코드를 짜기까지 시간이 걸리기도 하고, 코드 리뷰를 하면서 변수명이나 로직 자체에 대해서 의견을 제시하는 경우가 많다. (그냥 의견을 제시하는 것뿐이지만, 가끔씩 동료는 내가 딴지를 건다고 느끼는 것 같다. 😢)

 

때문에 보이지는 않지만 동료의 감정을 상하게 만든 것 같이 느껴질 때가 있다.
(제 소프트 스킬이 부족한 탓입니다.. 동료분들께 다시 한번 사과드립니다 🙇‍♂️🙇‍♂️)

그래도 이 부분을 읽으니 내가 가진 습관이 꼭 나쁜 습관은 아닌 것 같아서 조금이나마 위로가 된다.