[Python] DocStrings (독스트링) 작성

 

Python 대표이미지

 

필요성 

파이썬을 활용해 작업할 함수(Function)를 작성하고 다루던 중, 함수를 호출할 때에 유용하게 쓰일 수 있는 "Python 내 DocString"을 알게 됐습니다. 함수를 호출할 때면, 코드편집기 창에 덩달아 안내되는 함수 설명문구를 개발자가 직접 작성할 수 있고, 이를 통해 협업시 소통 또한 유용할 것 같아 기록을 남기고자 합니다. 

 

---

접근 (요약)

 

  1. Docstring 이란?

      (1.1) 정의, 특징

 

  2. Python에서의 코드 예시

      (2.1). (One-line / Mulit-line) Docstring

      (2.2). 함수 생성-선언

      (2.3). 코드편집기에서의 Python 속성에 접근

---

방법

  1. Docstring 이란?

 

      (1.1) 정의, 특징(작성법)

 

정의 : Docstring이란, 모듈, 함수, 클래스 또는 메소드 정의의 첫 번째 명령문으로 발생하는 문자열 리터럴입니다.

 

특징 1. 크게 "One-line Docstrings"과 "Multi-line Docstring"으로 구분될 수 있습니다.

특징 2. def 함수명(): 함수를 선언하고 다음 행에 """  """ 3쌍의 큰따옴표(double-quote)를 작성해 사용준비를 한다.

특징 3. 3쌍의 큰따옴표(double-quote) """Docstring 내용""" 사이에 작성할 내용을 기입한다.

특징 4. 타 행에서 함수명(), 함수를 호출해보면 코드편집기 내에 내가 작성한 Docstring이 드러난다.  

 

---

  2. Python에서의 코드 예시

 

      (2.1). (One-line / Mulit-line) Docstring

# One-line Docstring

def function(a, b):
    """function(a, b) -> list"""

# Multi-line Docstring

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
    ...

      (2.2). 함수 생성-선언

# 실제 예시
# title() 함수를 사용하도록 하는 예제

def format_name(f_name, l_name):
  """
  format_name 함수는 두 인자를 받아서 이를 title case version으로
  만들어 return 해주는 함수이다.
  """
  
  if f_name == "" or l_name == "": 
    return "You didn't provide valid inputs."
  formated_f_name = f_name.title()
  formated_l_name = l_name.title()

  return f"Result: {formated_f_name} {formated_l_name}"

 

      (2.3). 코드편집기에서의 Python 속성에 접근

 

위처럼, Docstring을 작성해준 함수를 타 행에서 타이핑하는 것만으로도 해당 함수에 대한 Docstring의 정보를 제공하는 것을 확인할 수 있다. (이를 python의 속성에 접근했다는 표현으로 썼다.)

 

---

이상으로, Python 내 Docstring을 작성 방법을 학습해봤습니다.

추가 질문을 댓글을 달아주시면 감사하겠습니다^^!

오늘도 파이팅입니다!