Docstring

docstring은 소스 코드에 포함된 문서(documentation)이다.

docstring은 기본적으로 리터럴 문자열이며, 로직의 일부분을 문서화하기 위해 코드 어딘가에 배치된다.

코드에 주석(comment)을 다는 것은 여러 가지 이유로 나쁜 습관이다.

1. 주석은 코드로 아이디어를 제대로 표현하지 못했음을 나타내는 것이다. 만약 무언가를 왜 어떻게 하는지 꼭 설명해야 한다면 그 코드는 아마도 충분히 좋지 못한 것이다. 이러한 코드는 초급자가 이해하기 어렵다.
2. 오해의 소지가 있다. 복잡한 내용을 이해하기 위해 시간을 할애하는 것보다 최악은 코드가 어떻게 동작하는지 주석을 확인한 후 실제로 동작하는 것의 다른 점을 파악하는 것이다. 그리고 사람들은 코드를 변경할 때 주석 업데이트를 깜빡하는 경우가 많으므로 방금 수정한 코드 근처의 주석이 현재와 일치하지 않을 경우 또 다른 위험을 초래할 수 있다.

드물지만 떄로는 주석을 피할 수 없는 경우도 있다. 외부 라이브러리에 오류가 있다면 짧은 주석을 다는 것이 허용된다.

 

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

 

docstring을 코드에 포함시키는 것이 좋은 이유는 (또는 프로젝트의 표준에 따라 필수일 수 도 있음) 파이썬이 동적 타이핑을 하기 때문이다. 예시로는 함수는 파라미터의 값으로 무엇이든 사용할 수 있다. 파이썬은 파라미터의 타입을 체크하거나 강요하지 않는다. 따라서 함수를 수정해야 하는데 함수의 이름과 파라미터의 이름이 충분히 설명적이라면 굉장히 운이 좋은 것이다. 그렇다 해도 아직 정확히 어떤 타입을 사용해야 하는지 알 수 없다.

 

이런 경우 docstring이 도움이 될 것이다. 예상되는 함수의 입력과 출력을 문서화하면 사용자가 사용할 때 함수가 어떻게 동작하는지 이해하기 쉽다.

 

예시)

 

예시와 마찬가지로 내가 작성한 코드에 docstring을 제공한다면 함수 사용자가 훨씬 수월하게 사용 방법을 익힐 수 있다.

docstring은 코드에서 분리되거나 독립된 것이 아니다. 코드의 일부가 되어 접근할 수 있어야한다. 객체에 docstring이 정의되어 있으면 __doc__ 속성을 통해 접근이 가능하다.

 

docstring의 한가지 단점은 지속적으로 수작업을 해야 한다는 것이다. 코드가 변경되면 업데이트를 해야한다. 또 다른 문제점을 docstring이 정말 유용하게 사용되려면 여러 줄에 걸쳐 상세하게 작성해야 한다는 것이다.

 

책 : 파이썬 클린코드