[Python] Docstring에 대하여
Docstring
docstring은 소스 코드에 포함된 문서(document)라고 말할 수 있습니다. docstring은 기본적으로 리터럴 문자열이며, 로직의 일부분을 문서화하기 위해 코드 어딘가에 배치됩니다.
문서(documentation)라는 단어에 주목해보면, "이유"가 아니라 "설명"입니다. 따라서 docstring은 주석을 다는 것이 아니라 코드의 특정 컴포넌트(모듈, 클래스, 메서드 또는 함수)에 대한 문서화입니다. 이런 컴포넌트에 사용하는 것은 허용될 뿐 아니라 권장되는 부분입니다. 가능한 많은 docstring을 추가하는 것이 좋습니다.
docstring을 코드에 포함시키는 것이 좋은 이유는 파이썬이 동적 타이핑을 하기 때문입니다. 예를 들어 함수는 파라미터의 값으로 무엇이든 사용될 수 있습니다.
표준 라이브러리에 docstring을 사용하는 좋은 예시가 있습니다. help() 함수를 통해 dict.update 메서드의 docstring이 출력한 예시 입니다. 출력된 정보는 함수가 어떻게 동작하는지 어떻게 활용될 수 있는지 이해하는데 매우 중요한 역할을 할 것입니다.
|
1
2
3
4
5
6
7
8
|
>>> help(dict.update)
Help on method_descriptor:
update(...)
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]
|
cs |
Docstring 작성
docstring은 Module의 첫번째 줄, 함수 선언 후 바로 아랫줄 또는 클래스 선언 후 내부 바로 아랫줄에 큰따옴표 3개나 작은 따옴표 3개로 작성할 수 있습니다
객체에 docstring이 정의되어 있으면 __doc__ 속성을 통해 접근이 가능합니다. 또한 위에서 사용한 것 처럼 help 함수를 이용하는 방법도 있습니다.
|
1
2
3
4
5
6
|
>>> def my_func():
... """임의로 만든 함수"""
... return None
...
>>> my_func.__doc__
'임의로 만든 함수'
|
cs |
Sphinx 소개
런타임 중에 접근하고 심지어 소스 코드에서 docstring 내용을 추가하거나 컴파일하는 것이 가능합니다. 실제로 이런 작업을 위한 도구가 있습니다. Sphinx(스핑크스)를 실행하면 프로젝트 문서화를 위한 기본 골격을 만들어줍니다.
https://www.sphinx-doc.org/en/master/
Overview — Sphinx documentation
Welcome What users say: “Cheers for a great tool that actually makes programmers want to write documentation!“ Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD lic
www.sphinx-doc.org
특히 autodoc 익스텐션(sphinx.ext.autodoc)을 사용하면 코드에서 docstring을 가져와 문서화된 페이지를 만들어 줍니다. 나중에 다른 포스팅에서 다루어보도록 하겠습니다.
문서화 도구를 사용할 준비가 되었으면 문서나 프로젝트와 하나가 되도록 해당 도구를 오픈해야 합니다. 오픈소스 프로젝트의 경우 브랜치나 버전별 문서를 자동으로 생성하도록 설정할 수도 있습니다. 가장 중요한 점은 모든 팀원이 문서화에 참여할 수 있어야 한다는 점입니다.
docstring의 단점
docstring의 단점도 있는데 모든 문서화가 그렇듯 지속적으로 수작업을 해야 한다는 점입니다. 즉 코드가 변경되면 업데이트를 해야합니다.
또 다른 문제점은 docstring이 유용하게 사용되려면 여러 줄에 걸쳐 상세하게 작성되야 한다는 점입니다.
적절한 문서를 유지하는 것은 소프트웨어 엔지니어로서 피할 수 없는 과제 입니다. 문서화에 수작업이 필요한 이유는 결국 다른 사람이 읽기 때문입니다. 가치 있는 문서를 만들기 위해서 모든 팀원이 문서화에 노력해야합니다.
핵심은 소프트웨어가 단순한 코드가 아니라는 것을 이해하는 것입니다.