코드 포매팅과 도구
목표
- 클린 코드가 무엇인지 이해한다.
- 클린 코드 작성이 왜 중요한지 이해한다.
- 왜 포매팅과 문서화가 중요한지 이해한다.
- 이 과정을 어떻게 자동화하는지 배운다.
클린 코드의 의미
프로그래밍 언어의 진정한 의미는 인간의 아이디어를 컴퓨터에게 전달하기 위한 언어가 아니라 아이디어를 다른 개발자에게 전달하는 것이다.
"클린 코드는 결국에는 전달이 잘 되는가의 목적이 있으므로 객관적으로 정의할 수는 없다. 이는 스스로 파이썬의 주요 개념을 이해한 다음 좋은 코드와 나쁜 코드의 차이점을 확인하고 훌륭한 코드와 좋은 아키텍처의 특징을 식별하여 자신만의 정의를 하는 것이 좋다"
클린 코드의 중요성
유지보수성 향상
클린 코드의 기대효과는 민첩한 개발과 지속적인 배포가 가능하다는 것
만약 프로젝트를 일정하게 예측 가능한 속도로 지속적으로 배포하려고 한다면 유지보수가 가능한 좋은 코드를 갖는 것이 필수적
기술 부채는 나쁜 결정이나 적당한 타협의 결과로 생긴 소프트웨어적 결함을 말한다. 코드는 지금 바꾸는 것보다 미래에 변경하는 것이 더 어렵기 때문에 '부채'라고 한다. 내일은 코드를 수정하기가 더 어렵고 비싸며, 내일 모레는 더더욱 비싸질 것
클린 코드가 필요없는 예외 사항
- 해커톤 참여
- 일회성 작업을 위한 간단한 스크립트를 작성하는 경우
- 프로그래밍 경진 대회 참여
- 기존에 없던 개념을 검증하기 위해 개발하는 경우
- 나중에 버려질 것이 확실한 프로토타입
즉 유지보수가 필요없다면, 고품질의 코드를 작성하기 위한 노력을 하지 않을 수 있다.
코드 포매팅
파이썬에서는 어떻게 코드를 작성하고 포매팅 해야 하는지에 대해 PEP-8과 같은 표준을 가지고 있다.
그러나 클린 코드는 코딩 표준, 포매팅, 린팅 도구나 다른 검사 도구를 사용한 코드 레이아웃 설정과 같은 것 그 이상을 뜻한다.
클린 코드는 품질 좋은 소프트웨어를 개발하고, 견고하고 유지보수가 쉬운 시스템을 만들고, 기술 부채를 피하는 것을 의미
그럼에도 포매팅에 주의를 기울이지 않으면 몇 가지 위험이 따른다.
프로젝트 코딩 스타일 가이드 준수
좋은 코드 레이아웃에서 가장 필요한 특성은 '일관성'이다. 코드가 일관되게 구조화되어 있으면, 가독성이 높아지고 이해하기 쉬워진다.
개발 팀의 모든 멤버가 표준화된 구조를 사용한다면 훨씬 익숙한 코드를 작성하게 될 것이고 신속하게 패턴을 파악할 수 있으며, 이러한 패턴을 염두에 두고 있다면 오류를 감지하는 것이 훨씬 쉽다.
파이썬에서는 구조적인 일관성을 맞출 때, PEP-8 코딩 스타일을 사용한다. 만약 현재 프로젝트가 어떤 코딩 표준도 따르지 않았다면, PEP-8을 사용하도록 하자. 이상적으로는 회사나 팀 차원에서 이미 준수해야 할 코딩 표준을 설명하는 문서가 있어야 한다.
PEP-8은 다음과 같은 특성을 가지고 있다.
검색 효율성
코드에서 원하는 부분을 빠르게 검색할 수 있도록 도와주는 성질
변수에 값을 할당하는 경우와 함수의 키워드 파라미터에 값을 할당하는 경우를 구분
일관성
코드가 일정한 포맷을 가지면 훨씬 쉽게 읽을 수 있다.
더 나은 오류 처리
PEP-8에서 제안한 것 중 하나는 try/except 블록 내부의 코드를 최소화하자는 것이다.
코드 품질
코드를 구조화하여 살펴보면 한 눈에 코드를 이해하고 버그와 실수를 쉽게 찾을 수 있다.
구조화(포매팅)은 클린 코드에서 필수적인 부분이지만, 문서화 방식이나 코드 품질 자동화 도구를 결정하는 데 있어서 많은 영향을 미친다.
문서화(Documentation)
파이썬 코드 안에 직접 문서화를 하는 방법에 대해서 배워본다.
훌륭한 코드는 그 자체로 분명하지만 문서화 또한 잘 되어 있다.
- 코드를 문서화하는 것은 코드에 주석을 추가하는 것과 다르다.
코드 주석(code comments)
가능한 한 적은 주석을 갖는 것을 목표로 해야 한다. 좋은 코드는 코드 자체가 문서화되어 있기 때문이다. 다시 말하면 올바른 추상화를 했고 명확하게 이름을 지정했다면 주석이 필요하지 않아야 한다는 것을 의미
주석을 작성하기 전에 새로운 함수를 추가하거나 보다 나은 변수명을 사용하는 것과 같은 방법으로 개선할 수 있는지 고민해보자
그러나 어떤 경우에는 주석을 추가하는 것을 피할 수 없으며 그렇게 하지 않으면 위험할 수 있다.
이런 경우에는 가능한 간결하게 문제가 무엇인지 설명하고 어떻게 해결해야 하는지 설명해야 한다.
또한 주석 처리된 코드는 무자비하게 바로 삭제되어야 한다.
Docstring
Docstring은 소스 코드에 포함된 문서라고 말할 수 있다.
기본적으로 로직의 일부분을 문서화하기 위해 코드 어딘가에 배치된다. 설명을 위한 것
Docstring은 모듈, 클래스, 메서드 또는 함수에 대해 문서를 제공하기 위한 것이다. 내가 작성한 컴포넌트를 다른 엔지니어가 사용하려고 할 때, docstring을 보고 동작방식과 입출력 정보 등을 확인할 수 있어야 한다. 최대한 docstring을 추가하려고 노력하는 것은 좋은 습관이다.
Docstring을 가진 코드가 좋은 이유는 파이썬이 동적인 데이터 타입을 갖기 때문이다. 즉, 파이썬의 함수는 파라미터 값으로 어떤 데이터 타입도 취할 수 있다.
가령 함수를 수정한다고 가정할 때, 함수의 이름이나 파라미터는 꽤 설명적인 이름을 가지고 있지만, 여전히 어떤 데이터 타입을 전달해야 하는지는 여전히 명확하지 않을 수 있다.
표준 라이브러리의 좋은 docstring 예시를 살펴보자.
dict.update??을 작성하면 다음과 같은 dict.update 메서드의 docstring이 출력된다.
Docstring:
D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
In either case, this is followed by: for k in F: D[k] = F[k]
Type: method_descriptor
객체에 docstring이 정의되어 있으면 __doc__ 속성을 통해 접근이 가능하다.
def my_function():
return None
...
my_function.__doc__이런 작업을 위한 도구 Sphinx(스핑크스)를 실행하면 프로젝트 문서화를 위한 기본 골격을 만들어준다. 특히 autodoc 익스텐션을 사용하면 코드에서 docstring을 가져와 문서화된 페이지를 만들어준다.
docstring의 단점은 지속적으로 수작업을 해야 한다는 것 코드가 변경되면 업데이트를 해야한다. 이러한 점을 볼 때, 함수가 너무 간단하고 자명한 코드라면 중복된 의미를 가진 docstring을 피하는 것이 더 나은 선택일 수 있다.
