본 실습에서는 Python 코드에 docstring 을 사용하여 문서화하는 것의 중요성에 대해 배웁니다. help() 함수와 __doc__ 속성을 사용하여 내장 함수 (built-in functions) 의 기존 docstring 에 접근하는 방법을 탐구할 것입니다.
더 나아가, 사용자 정의 함수 (custom functions) 에 대한 docstring 을 직접 작성하고 그 접근성을 검증하는 실질적인 경험을 쌓아, 본인과 타인이 코드를 더 쉽게 이해하고 유지보수할 수 있도록 할 것입니다.
help()를 사용하여 문서 접근하기docstring 은 모듈, 함수, 클래스 또는 메서드 정의에서 첫 번째 구문으로 나타나는 문자열 리터럴 (string literal) 입니다. 이는 코드가 무엇을 하는지 문서화하는 데 사용됩니다. Python 의 내장 함수인 help()는 이 문서를 깔끔하고 읽기 쉬운 형식으로 보는 데 탁월한 도구입니다. help() 함수는 대화형 사용 (interactive use) 을 위해 설계되었습니다.
내장 함수인 print() 함수의 문서를 보는 것으로 시작하겠습니다.
먼저, WebIDE 에서 터미널을 엽니다. 화면 상단의 Terminal 메뉴를 클릭하고 New Terminal을 선택하여 이 작업을 수행할 수 있습니다.
터미널에서 다음 명령어를 입력하고 Enter 키를 눌러 Python 대화형 셸 (interactive shell) 을 시작합니다.
pythonPython 프롬프트 (>>>) 가 나타납니다. 이제 help() 함수를 사용하여 print()에 대한 정보를 얻습니다.
help(print)터미널에 print 함수의 문서가 표시됩니다.
Help on built-in function print in module builtins:
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
(END)이 출력은 함수가 하는 일, 허용하는 매개변수 및 해당 기본값을 설명합니다. q 키를 눌러 도움말 뷰어 (help viewer) 를 종료하고 Python 프롬프트로 돌아갑니다.
이제 다음을 입력하여 Python 대화형 셸을 종료합니다.
exit()__doc__를 사용하여 원시 Docstring 접근하기help()는 대화형 사용에 훌륭하지만, 객체의 특수 속성인 __doc__를 사용하여 프로그램 방식으로 원시 docstring 에 접근할 수도 있습니다. 이 속성은 docstring 을 일반 문자열로 보유합니다.
이것이 실제로 어떻게 작동하는지 살펴보겠습니다. 왼쪽 WebIDE 파일 탐색기에서 access_docstring.py라는 파일을 찾아 엽니다.
파일에 다음 Python 코드를 추가합니다. 이 코드는 내장 함수인 len() 함수의 docstring 을 출력합니다.
## This script prints the docstring of the len() function.
print(len.__doc__)파일을 저장합니다 (단축키 Ctrl+S를 사용할 수 있습니다).
이제 터미널로 돌아가 다음 명령어로 스크립트를 실행합니다.
python access_docstring.py출력 결과는 len 함수의 원시 docstring 이 될 것입니다.
Return the number of items in a container.보시다시피, __doc__는 문서의 직접적인 문자열 내용을 제공하며, 이는 문서를 처리하는 사용자 정의 도구나 스크립트에 유용할 수 있습니다.
자신의 함수를 문서화하는 것은 깔끔하고 유지보수 가능한 코드를 작성하는 기본적인 관행입니다. 좋은 docstring 은 함수의 목적, 매개변수 및 반환 값을 설명해야 합니다.
함수를 작성하고 문서화해 보겠습니다. 파일 탐색기에서 my_function.py 파일을 엽니다.
먼저, 파일에 다음 함수 정의를 추가합니다.
def greet(name, greeting="Hello"):
print(f"{greeting}, {name}!")이제 docstring 을 추가해 보겠습니다. docstring 은 def 줄 바로 다음에 위치해야 하며 함수의 코드와 동일한 수준으로 들여쓰기 되어야 합니다. 여러 줄 docstring 을 위해 삼중 따옴표 ("""...""") 를 사용할 것입니다.
docstring 을 포함하도록 my_function.py를 수정합니다. 또한, 작동 여부를 확인하기 위해 docstring 을 출력하는 줄을 추가하겠습니다.
def greet(name, greeting="Hello"):
"""Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".
"""
print(f"{greeting}, {name}!")
## Print the docstring of our greet function
print(greet.__doc__)파일을 저장합니다. 이제 터미널에서 스크립트를 실행합니다.
python my_function.py콘솔에 사용자 정의 docstring 이 출력되는 것을 볼 수 있습니다.
Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".이를 통해 함수를 성공적으로 문서화했으며 __doc__ 속성을 사용하여 해당 docstring 에 접근할 수 있음을 확인할 수 있습니다.
help() 사용하기이전 단계에서는 __doc__를 사용하여 사용자 정의 docstring 에 접근했습니다. 이제 help() 함수를 사용하여 내장 함수인 print() 함수에서 했던 것처럼, 더 세련되고 사용자 친화적인 방식으로 문서 보기를 확인해 보겠습니다.
help()를 사용하기 위해 greet 함수를 Python 인터랙티브 셸로 가져오겠습니다.
터미널에서 Python 셸을 다시 시작합니다.
python>>> 프롬프트가 보이면 my_function 모듈 (파일명 my_function.py는 my_function이라는 모듈로 취급됨) 에서 greet 함수를 가져옵니다.
from my_function import greet이제 help()를 사용하여 greet 함수의 문서를 확인합니다.
help(greet)docstring 에서 생성된 깔끔하게 포맷된 출력을 보게 될 것입니다.
Help on function greet in module my_function:
greet(name, greeting='Hello')
Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".
(END)help()가 함수의 시그니처 (greet(name, greeting='Hello')) 를 자동으로 포함하고 가독성을 위해 docstring 을 포맷하는 방식을 확인하십시오. 이것이 좋은 docstring 을 작성하는 것이 매우 가치 있는 이유입니다. 이는 Python 의 내장 도움말 시스템과 직접 통합되기 때문입니다.
도움말 뷰어를 종료하려면 q를 누르고, Python 셸을 나가려면 exit()를 입력하십시오.
본 실습에서는 docstring 을 사용하여 Python 코드를 문서화하는 기본 사항을 배웠습니다. 인터랙티브 help() 함수와 __doc__ 속성을 사용하여 내장 함수의 문서를 접근하는 연습을 했습니다. 그런 다음, 표준 관례를 따라 사용자 정의 함수에 대해 단일 행 및 다중 행 docstring 을 작성함으로써 이 지식을 적용했습니다. 마지막으로, 사용자 정의 문서가 __doc__와 Python 의 help() 시스템 모두를 통해 접근 가능하다는 것을 확인했으며, 이는 읽기 쉽고 재사용 가능하며 유지보수 가능한 코드를 작성하는 핵심 기술입니다.
