[Python] Docstring & Annotation 닥스트링과 어노테이션

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

                 -코드에 포함된 문서(documentation) --> 이유가 아니라 설명

 

주석(comment) ≠ 문서

 

 

docstring은  주석을 다는 것이 아니라 코드의 특정 컴포넌트에 대한 문서화이다

가능한 많은 docstring을 포함하는 것이 좋다

docstring을 코드에 포함시키는 것이 좋은 이유는 파이썬이 동적 타이핑을 하기 때문이다.

   --> 파이썬은 파라미터의 타입을 체크하거나 강요하지 않기 때문에, 예상되는 함수의 입력과 출력을 문서화하면 사용자가 사용할 때 함수가 어떻게 동작하는지 이해하기 쉽다

 

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

 

annotation을 사용해 변수의 예상 타입을 지정할 ㅜㅅ 있다.

실제로는 타입뿐 아니라 변수를 이해하는데 도움이 되는 어떤 형태의 메타데이터라도 지정할 수 있다

 

 

annotation은 docstring을 대체할 수 있을까?

docstring과 annotation은 서로 보완적인 개념이다

docstring에 포함된 정보의 일부는 어노테이션으로 이동시킬 수 있는 것이 사실이다

그러나 docstring을 통해 보다 나은 문서화를 위한 여지(어떤 형태의 데이터를 다루는지 제공)를 남겨두어야 한다

 

 

참고: 파이썬 클린코드(마리아노 아나야)