[파이썬 기초] 파이썬 문서화(Docstring), 주석 사용법

무지를 아는 것이 곧 앎의 시작이다
- 소크라테스

 

  이전 글에서 내가 작성한 파이썬 코드가 잘 작성되었는지 확인해볼 수 있는 PyLint를 사용하는 방법에 대해서 알아보았습니다.

[A. Programming/Python] - 파이썬(Python) PyLint 사용해보기

파이썬(Python) PyLint 사용해보기

 

  본격적인 파이썬 코딩에 앞서 한 가지만 더 알아두고 가면 좋을 것 같아서 이에 대해서 알아보려고 합니다. 여기서 알아보려고 하는 것은 파이썬 문서화와 관계된 Docstring이란 것입니다. 파이썬에서 기본적으로 제공하는 기능 중 하나이며, 추가적인 설치 없이 간편하게 사용이 가능합니다.

 

 

 파이썬 Docstring

 

  Docstring은 PEP257에 기술되어 있으며, 아래의 공식 사이트에서 정보를 확인하실 수 있습니다.

- https://www.python.org/dev/peps/pep-0257/

PEP 257 -- Docstring Conventions

 

  Docstring은 파이썬의 클래스, 모듈 등의 정의 시 사용하여 해당 기능에 대한 설명을 문서화할 수 있도록 해줍니다. 이렇게 문서화된 내용은 해당 객체의 __doc__ 특수 속성으로 추가되며, help()나 __doc__를 이용하여 확인할 수 있습니다.

 

  사용방법은 클래스나 모듈 선언 후 바로 아래 첫 번째 줄에 큰따옴표(")나 작은따옴표(') 3개로 작성이 가능하지만, 일관성을 위해서 큰따옴표 3개(""")로 작성하는 것을 권고하고 있습니다. 보통 모듈의 기능, 파라미터 및 리턴값에 대한 설명을 작성하며 구글 스타일 가이드를 많이 참조하고 있습니다. 구글 스타일 가이드는 아래의 사이트에서 확인하실 수 있습니다.

- http://google.github.io/styleguide/pyguide.html

styleguide

 

  아래와 같이 한 줄 또는 여러 줄의 경우에도 사용이 가능하며, 이 때도 들여쓰기는 지켜서 사용을 해주어야 합니다.

 

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

 

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

 

  위에서 작성한 예제를 작성한 후 help() 또는 __doc__의 값을 보면 위에서 작성한 Docstring이 표시되는 것을 알 수 있습니다.

 

 

 

  Docstring을 일종의 주석으로 활용할 수도 있지만 주석과는 분리해서 사용하는 것이 좋다고 생각합니다. Docstring과 주석 둘 다 프로그램 실행에 영향을 주진 않지만 Docstring은 __doc__ 특수 속성에 추가되기 때문에 다릅니다.(주석은 개발자를 위한 소스코드에 대한 설명이라면 Docstring은 클래스나 모듈 사용자를 위한 것이라고 볼 수 있습니다.)

 

  그럼 파이썬의 주석은 어떻게 사용하는지에 대해서도 알아보도록 하겠습니다.

 

 

 파이썬 주석

 

  주석은 코딩 과정에서 매우 유용하고 다양하게 활용이 되는데 파이썬의 주석은 샵(#) 기호를 이용하여 사용할 수 있습니다.

 

# python example
def python_exam():
    print("Python test")

 

# python example
# def python_exam():
    # print("Python test")

 

  여러 줄에 걸쳐 주석 처리를 해야될 경우 따옴표 3개를 이용하여 하는 경우도 있는데 이보다는 각 줄마다 샵(#) 기호를 이용하여 주석 처리하는 것이 보다 목적에 맞는 활용이라고 생각합니다.

 

  대부분의 IDE 및 텍스트 에디터와 같은 툴에서 여러줄 주석을 단축키를 통해 간단하게 설정 및 해제를 할 수 있기 때문에 이를 활용한다면 좋을 것 같습니다.

 

노트패드++(Notepad++) : Ctrl + q

파이참(PyCharm) : Ctrl + /

 

 

 파이썬의 Docstring과 주석

 

  파이썬 코딩을 시작하기 전에 무엇을 더 알고 시작하는 것이 좋을까 생각하던 중 Docstring을 알고 시작하는 것이 좋을 것 같아서 다루어 보았습니다.

 

  사실 문서화나 주석을 추가하는 것 자체가 다소 번거로운 작업일 수 있지만, 프로젝트가 커지고 프로그램의 기능이 많아지면 자신이 만든 클래스나 모듈에 대해서도 헷갈리는 경우가 생기기 마련입니다. 처음부터 이런 문서화 습관을 기를 수 있다면 좋을 것 같아 다루어 보았습니다.

 

  이제 다음 파이썬 관련 글부터는 파이썬 코딩의 기초부터 하나씩 작성해보려고 합니다.