[파이썬] 파이썬 문서화에 유익한 '독스트링(docstring)'

문서화에 유익한 '독스트링(docstring)'

독스트링(docstring)은 파이썬에서 함수, 클래스, 모듈 또는 메서드의 첫 번째 문장으로 작성되는 문자열입니다. 이 문자열은 해당 객체의 목적, 동작 방식 및 사용 방법을 설명하는 데 사용됩니다. 독스트링은 파이썬의 help() 내장 함수를 통해 접근할 수 있고, 다양한 문서화 도구에서 자동으로 정보를 추출하여 문서화하는 데 사용됩니다.

독스트링 세 가지 주요 형식

한 줄 독스트링

한 줄 독스트링은 간결한 설명으로, 객체가 하는 일을 요약합니다.

여러 줄 독스트링

여러 줄 독스트링은 보다 상세한 설명을 제공하며, 일반적으로 세 부분으로 나뉩니다. 요약, 확장 설명, 그리고 파라미터 및 반환값에 대한 설명입니다.

클래스 독스트링

클래스에 대한 독스트링은 클래스의 목적과 사용 방법을 설명합니다. 또한 주요 메서드와 속성에 대한 정보를 포함할 수 있습니다.

 

독스트링은 특별한 문자열 구문이 아니라, 단순히 해당 객체 바로 아래에 위치하는 문자열 리터럴입니다. 이 문자열은 객체의 __doc__ 속성으로 자동 저장되며, 프로그램 실행 중에도 이를 통해 접근할 수 있습니다.

 

효과적인 독스트링

• 간결하고 명확한 설명: 객체가 무엇을 하는지를 간단하고 명확하게 설명해야 합니다.
• 매개변수: 함수나 메서드의 매개변수에 대한 설명을 포함해야 합니다.
• 반환값: 반환값의 타입과 그 의미를 설명해야 합니다.
• 예외: 객체가 발생시킬 수 있는 예외에 대해 설명해야 합니다.
• 사용 예제: 사용자가 객체를 어떻게 사용해야 하는지를 보여주는 하나 이상의 예제가 포함되면 도움이 됩니다.

이러한 방식으로 작성된 독스트링은 코드의 가독성과 유지보수를 크게 향상시키며, 자동 문서화 도구가 사용하기에 적합합니다.