[python] PEP , PEP 257 (Docstring Conventions)

 

PEP 257은 파이썬 개발자 가이드 일부로 작성된 문서로,

docstring의 고수준 구조를 표준화하기 위한 문서이다.

docstring을 사용하여 파이썬 코드를 문서화하기 위한 규칙, 모범사례, 의미론을 알아보자.

1. docstring 에는 무엇이 포함되어야 할까?
2. docstring 은 어떻게 사용해야 할까 ?

docstring이란 무엇일까?

모듈, 함수, 클래스 또는 메서드 정의의 첫번째 문장으로 나타내는 문자열 리터럴이다.

이러한 docstirng 은 해당 객체의 __doc__ 특수 속성이 된다.

다시 말해 dicstring은 클래스, 모듈, 함수, 메서드 정의에 사용되는 파이썬 문서화 문자열이며,

보다 큰 코드의 기능에 대한 정보를 구체적인 방식으로 제공한다.

이러한 코드는 작성자를 포함해 해당 코드를 읽는 모든 프로그래머가 기능을 이해하고 기억하는데 도움을 준다.

 

독스트링(docstring)과 주석(comments)의 차이는 무엇일까? 

우선 이 차이를 이해해야한다.

주석은 코드에 해당 코드들의 설명을 달 때 사용되고,

독스트링은 코드를 문서화 하기 위해 사용한다.

주석(comment)	독스트링(docstring)
파이썬에서 실행할 수 없는 문장. 인터프리터에서 무시된다. 메모리에 저장되지 않고, 실행중 접근할 수 없다	소스 코드를 읽거나 __doc__속성이나  help함수를 사용하여 접근할 수 있다.
목적은 코드의 가독성과 이해도를 높이고 코드를 의미 있게 설명하는 데 있다. 코드를 수정, 확장, 유지 관리하고 싶어 하거나 그럴 필요가 있는 사람들의 이해를 돕기 위한 목적이 크다.	목적은 코드를 문서화 하기 위함이다. 즉 코드의 사용법, 기능, 성능을 해당 코드를 사용하는 사람들, 즉 코드의 작동 방식을 알 필요 없는 사용자가 사용중에 확인 할 수 있는 내용이다.
주석은 문서화로 전환할 수 없다. 주석의 목적은 코드를 단순화하고 정확한 정보를 제공하여, 의도를 이해하는 데 도움이 되는 것이다.	모듈이나 함수의 동작, 매개변수의 의미, 특정 패키지의 목적 등을 설명하는 실제 문서로 쉽게 변환할 수 있다.

 

두 경우의 목적에 대한 부분을 안 짚고 넘어갈 수 없다.

기본적으로 우리는 귀도 반 로섬의 간단한 규칙을 잊어서는 안된다.

"Code is more often read than written."

우리가 작성하는 코드는 내가 작성하는 순간 보다, 읽히는 경우가 더 많다는 것을 잊지 말아야 한다.

그러므로, 다른 개발자나 사용자가 이해할 수 있도록 프로그래밍 코드 작성 습관을 들이는 것이 중요하다.

이를 통해서 코드 재사용과 기여도가 높아질 것이다.

따라서 docstring은 더 깔끔하고, 읽기 쉽고, 더 지속 가능한 코드를 유지하는 데 도움이 된다.

즉, 책임감 있는 개발자가 일상적인 프로그래밍 워크숍 툴 일부로 채택해야할 모범 사례 중 하나이다.

---

주석은 언제 사용하는 걸까 ?

주석은 몇 가지 다른 용도로 사용될 수 있다.

• 나중에 수행될 코드 섹션이나 추가 개선을 위해 남겨둔다.

# TODO : Add a function that takes the val and prc arguments.

• 테스트 하려는 코드 섹션에 주석을 달거나 주석 처리 해제 하는데 사용한다.

def fun(val):
  return val * 2

user_value = int(input("값을 입력하세요 : "))
#fun(user_value)
#user_value = user_value + "foo"

print(fun(user_value))

 

• 작업 계획, 디자인할 코드 특정 섹션을 개략적으로 설명하는 데 사용한다.

# Step 1 : Ask the user for the value.
# Step 2 : Change the value to an int and handle possible exceptions.
# Step 3 : Print the value multiplied by 0.7.

---

Type hints : PEP 484

타입 힌트는 Python 3.5에 도입되어 PEP 484 에 정의된 메커니즘으로,

주석 없이 코드에 추가 정보를 추가할 수 있도록한다.

선택사항이나, 좀 더 정형화된 기능으로, Python 내장 모듈 typing 을 사용해 

타입 힌트 정보를 제공하여 특정 제안을 남기고, 개발 과정에서 발생할 수 있는 문제를 표시하고, 특정 이름에 타입 정보를 레이블로 지정할 수있다.

간단히 말해서 타입힌트를 사용하면, 파이썬 객체와 관련된 타입 정보를 정적으로 나타낼 수 있다.

예를 들면 함수에 타입 정보를 추가할 ㅅ 있다.

즉, 함수가 받는 인수의 타입이나 반활할 값의 타입을 지정한다.

#타입 힌트 없는 경우
def hello(name):
  return "Hello" + name

#타입 힌트 있는 경우
def hello(name:str) -> str:
  return "Hello" + name

타입 힌트는 선택 사항 이므로, PEP 484는 코드에 정적 타입 정보를 남겨둘 것을 의무화 하지 않는다.

• (name: str) : 함수에 전달될 인자가 문자열이여야 함을 나타내며, 특정 상황의 위험을 최소화 한다.
• -> str :  함수가 문자열을 반환될 것임을 나타낸다.

파이썬에서 타입 힌트가 어떤 의미가 있을까 ?

그리고 타입 힌트를 어떻게 활용할 수 있을까?

 

• 코드를 문서화 하는 데 도움을 준다.

인수 및 응답 정보를 docstring에 남겨두는 대신 언어 자체를 이러한 목적으로 사용할 수 있다.

이는 프로젝트에서 코드를 게시하거나 다른 개발자와 공유하고, 나중에 소스코드를 확인해야할 때 

중요한 코드 정보를 강조하는 유용한 방법이 된다.

일부 대규모 소프트웨어 개발 프로젝트에서는 팀이 코드에서 타입이 실행되는 방식을 더 잘 이해하는 데 도움이 되는 타입 힌팅을 권장한다.

• 특정 유형의 오류를 더 효과적으로 파악하고 깔끔한 코드를 작성할 수 있다.

타입 힌트를 통해 코드의 타입을 신중하게 고려하게 되므로,

파이썬의 동적 특성으로 인해 발생할 수있는 오류를 예방하는데 도움이 된다.

단, 파이썬은 정적 타이핑을 요구하지 않는다.

• 타입 힌트는 런타임에 사용되지 않는다.

코드에 주석 형태로 남겨둔 모든 타입 힌트는 프로그램 실행시 삭제된다.

즉, 주석과 같이 코드 작동에 아무런 영향을 미치지 않는다.

반면 편집기나 IDE에 연결할 수 있는 타입 검사 시스템이나, Lint와 같은 도구를 함께 사용하면, 

코드 실행 전에 타이핑을 자동 완성하고 오류를 찾아 강조 표시되며 코드 작성을 지원할 ㅅ 있다.

• 런타임에 영향을 미치지 않으므로, 성능에도 영향을 미치지 않는다.

소스코드에 영향을 미치지 않으므로, 당연하게도 성능 시간에 영향을 미치지 않는다.

파이썬에서 런타임에 무시되므로, 컴파일 속도 향상에 영향을 미치지 않는다.

 

자세한 사항은 링크를 통해 PEP 484를 확인해 볼 수 있다.

https://peps.python.org/pep-0484/

PEP 484 – Type Hints | peps.python.org

 

---

Docstring

docstring은 클래스, 모듈, 함수, 메서드 정의에서 사용할 수 있다.

docstring 이 반드시 포함되어야 하는 경우도 있다.

더 정확히 말하면, 특정 모듈에서 내보내는 모든 공개 모듈, 함수, 클래스 및 메서드에는 docstring 이 있어야 한다.

 

비공개 메서드는 docstring을 할 필요가 없지만, def 뒤에 실제 기능을 설명하는 줄을 남기는 것이 좋다.

패키지 __init__.py 의 경우에도 문서화해야하며, 패키지 폴더 내 파일의 모듈 docstring에 패키지 docstring을 작성할 수 있다.

 

docstring은 모듈, 함수, 클래스 또는 메서드의 첫 번째 문장으로 나타나는 문자열 리터럴이다.

하지만 문자열 리터럴은 파이썬 코드 여러곳에서 작성할 수 있고, 문서화 역할을 할 수 있다.

더 이상 런타임 객체 속성으로 접근할 수 없더라도, 특정 소프트 웨어 도구를 통해 추출할 수 있다.

 

자세한 내용은 아래 링크를 참조하여 확인할 수 있다.

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

PEP 257 – Docstring Conventions | peps.python.org

 

• attribute docstrings

모듈 속성, 클래스 속성, __init__() 메서드 정의를 통한 인스턴스 속성은 최상위 레벨의 할당문 바로 뒤에 위치한다.

Docutils와 같은 추출 도구는 이들을 할당 정의 대상의 docstring으로 본다.

attribute docstring에 대해 자세히 알고 싶다면 PEP 224를 살펴볼 수 있다.

g = 'module attribute (module-global variable)'
"""This is g's docstring."""

class AClass:

    c = 'class attribute'
    """This is AClass.c's docstring."""

    def __init__(self):
        """Method __init__'s docstring."""

        self.i = 'instance attribute'
        """This is self.i's docstring."""

def f(x):
    """Function f's docstring."""
    return x**2

f.a = 1
"""Function attribute f.a's docstring."""

https://peps.python.org/pep-0258/#attribute-docstrings

PEP 258 – Docutils Design Specification | peps.python.org

 

• additional docstrings

추가적으로 위치하는 docstring을 의미한다.

해당 아이디어는 PEP 216에서 시작되었고, PEP 287로 대체되었다.

def function(arg):
    """This is __doc__, function's docstring."""
    """
    This is an additional docstring, ignored by the byte-code
    compiler, but extracted by Docutils.
    """
    pass

https://peps.python.org/pep-0258/#additional-docstrings

PEP 258 – Docutils Design Specification | peps.python.org

---

docstring 형태

docstring 에는 2가지 형태가 있다.

문서 제공을 위한다는 동일한 목적을 수행하지만,

어떤 docstring을 사용할지는 제공해야 할 정보의 양과 같은 특정 조건에 따라 달라진다.

• Single-line docstring

def func():
  """One-line description."""
  pass

간단하고 짧은 설명에 사용되고 한 줄에 맞아야 한다.

열고 닫는 따옴표가 같은 줄에 위치해 깔끔함을 유지 할 수 있다.

docstring은 코드를 설명하는 것이 아닌 규정하는 것이다.

다시말해 명령문의 형태를 취해야 한다.

def greeting(name):
  """Take a name and return its replicated form."""
  return name * 2

 

단순히 함수나 메서드 매개변수를 반복하는 것이 아닌 다음과 같은 형태여야 한다.

#나쁜 사례 : 함수나 매개변수를 그대로 작성
def fun(x,y):
  """fun(x,y) -> list"""

#교정 후 
def fun(x,y):
  """Compute the angles and return a list of coordinates."""

클래스의 docstring이 아니라면 docstring의 위나 아래의 빈줄을 두지 말것.

# 빈 줄 사례
def calculate_tax(x,y):

  """I am a one-line docstring."""

  return (x+y) * 0.25

# 교정 후 
def calculate_tax(x,y):
  """I am a one-line docstring."""
  return (x+y) * 0.25

 

 

• Muti-line docstring

한줄로 표현하기 어려운 경우 사용되고, 요약줄 밑에 빈줄 하나와 더 자세한 설명을 추가 구성하는 형식이다.

# Muti-line docstring
def func():
  """Summary line description.
  
  More elaborate description.
  ...
  ...
  """
  pass

 

여러 줄로 작성되는 경우, 열린 따옴표와 같은 수준의 들여쓰기를 사용한다.

def king_creator(name="Greg", ordinal="I", country="Neverland"):
  """Create a king following the article title naming convention.
  
  Keyword arguments:
  :arg name: the king's name (default: "Greg")
  :type name: str
  :arg ordinal: the king's ordinal (default: "I")
  :type ordinal: str
  :arg country: the king's country (default: "Neverland")
  :type country: str
  """
  pass

• class docstring

docstring의 주제에 맞춰 2중 줄을 삽입한다.

스크립트의 기능, 명령줄 구문, 환경 변수 및 파일을 문서화한다.

설명은 신규 사용자가 스크립트 사용법을 이해하는 데 도움이 되도록 균형있게 구성하고,

숙련된 사용자에게 프로그램의 모든 기능에 대한 빠른 참조를 제공한다.

클래스의 동작을 요약하고 공개 메서드와 인스턴스 변수를 문서화 한다.

# class docstring
class Vehichle:
  """A class to represent a Vehicle.
  
  Attribute:
  ----------
  vehicle_type : str
    The type of the vehicle, e.g. a car.
  id_number : int
    The vehicle identification number.
  is_autonomous: bool
    sef-driving -> True, not self-driving -> False

  
  Method:
  ----------
  report_location(lon=45.00, lat=90.00)
    Print the vehicle id number and its current location.
    (default longutude=45.00, default latitude=90.00)
  """

  def __init__(self, vehicle_type, id_number, is_autonomous=True):
    """
    Parameters
    ----------
    vehicle_type : str
      The type of the vehicle, e.g. a car.
    id_number : int
      The vehicle identification number.
    is_autonomous: bool
      self-driving -> True, not self-driving -> False
    """

  
    self.vehicle_type = vehicle_type
    self.id_number = id_number
    self.is_autonomous = is_autonomous

  def report_location(self, id_number, lon=45.00, lat=90.00):
    """
    Print the vehicle id number and its current location.
    
    Parameters
    ----------
    id_number : int
      The vehicle identification number.
    lon : float
      The vehicle's longitude.(default is 45.00)
    lat : float
      The vehicle's latitude.(default is 90.00)
    """
    pass

 

• module docstring

모듈에서 내보낸 클래스, 예외, 함수가 나열되어야 한다.

• package docstring(__init__.py의 docstring) 

패키지에서 내보내는 모듈과 하위 패키지가 나열되어야 한다.

• function / method docstring

해당 함수 및 메서드의 동작을 요약하고 , 값, 예외, 제한 사항등에 대한 정보를 제공한다.

---

Docstring 형식 유형

위의 두 예제를 보면, 조금 다른 docstring의 형식을 볼 수 있다.

• reStructuredText 형식

일반 텍스트만으로는 인라인 문서화에 충분히 표현력이 부족할 때,

풍부하고 확장 가능하면서도 읽기 쉬운, '보이는 대로'를 의미하는 일반 텍스트 마크업 구문이다.

PEP 287에 설명된 파이썬 문서 표준이다.

def king_creator(name="Greg", ordinal="I", country="Neverland"):
  """Create a king following the article title naming convention.
  
  Keyword arguments:
  :arg name: the king's name (default: "Greg")
  :type name: str
  :arg ordinal: the king's ordinal (default: "I")
  :type ordinal: str
  :arg country: the king's country (default: "Neverland")
  :type country: str
  """
  pass

https://peps.python.org/pep-0287/

• NumPy/SciPy docstring 형식

Google docsstring 형식과 reStructedText 형식을 결합한 것이다.

class Vehichle:
  """A class to represent a Vehicle.
  
  Attribute:
  ----------
  vehicle_type : str
    The type of the vehicle, e.g. a car.
  id_number : int
    The vehicle identification number.
  is_autonomous: bool
    sef-driving -> True, not self-driving -> False

  
  Method:
  ----------
  report_location(lon=45.00, lat=90.00)
    Print the vehicle id number and its current location.
    (default longutude=45.00, default latitude=90.00)
  """

  def __init__(self, vehicle_type, id_number, is_autonomous=True):
    """
    Parameters
    ----------
    vehicle_type : str
      The type of the vehicle, e.g. a car.
    id_number : int
      The vehicle identification number.
    is_autonomous: bool
      self-driving -> True, not self-driving -> False
    """

  
    self.vehicle_type = vehicle_type
    self.id_number = id_number
    self.is_autonomous = is_autonomous

  def report_location(self, id_number, lon=45.00, lat=90.00):
    """
    Print the vehicle id number and its current location.
    
    Parameters
    ----------
    id_number : int
      The vehicle identification number.
    lon : float
      The vehicle's longitude.(default is 45.00)
    lat : float
      The vehicle's latitude.(default is 90.00)
    """
    pass

 

https://numpydoc.readthedocs.io/en/latest/format.html

https://google.github.io/styleguide/pyguide.html#38-commets-and-docstrings

 

두 형식 모두 docstring을 만드는 데 적합하고, 두가지 모두 가장 인기 있는 파이썬 문서 생성기 중 하나인 Sphinx에서 지원한다.

https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html

Sphinx는 소프트웨어 개발 프로젝트의 문서 작성에 매우 유용한 도구이;다.

마크업 언어로 reStructuredText를 사용하며, HTML 출력 형식 지원, 코드 테스트, 광범위한 상호 참조, 문서 트리를 정의할 수 있는 계층 구조 등 다양하고 유용한 기능을 제공한다.

 

프로젝트를 문서화 하는 방법

파이썬 프로젝트를 문서화 할 때에는 프로젝트의 성격(공개/비공개, 오픈소스/공개 도메인)에 따라

가장 먼저 사용자를 정의하고 그들의 요구를 고려해야한다.

user persona를 만드는 것이 유용할 수 있는데 이는 사용자가 프로젝트를 어떻게 사용할지 파악하는 데 도움이 된다.

즉, 코드를 어떻게 활용할지 고민하고 코드를 사용할 때 발생할 수 있는 가장 일반적인 문제를 예측함으로 사용자 경험을 쉽게 개선할 수 있다.

일반적으로 프로젝트에는 아래와 같은 문서 요소들이 포함되어야 한다.

• readme : 프로젝트에 대한 간략한 요약, 목적, 일부 설치 지침 제공
• example.py : 프로젝트 활용 방법에 대한 예시 스크립트
• license.txt : txt파일 형식의 라이센스(특히, 오픈소스 및 공개 도메인 프로젝트시 중요함)
• how to contribute : 프로젝트에 기여할 수 있는 가능한 방법(공유, 오픈소스, 공개 도메인 프로젝트)에 대한 정보 제공 파일

코드를 문서화 하는 일은 꽤나 시간이 많이 걸리고 지치는 작업이 될 수 있으므로, 원하는 형식으로 문서를 자동 생성하고, 효과적인 방식으로 문서 업데이트 및 버전 관리를 처리하는 도구들을 사용하는 것이 좋다.

이미 언급했던 Sphinx나 pdoc 등 다양한 문서화 도구와 리소스가 있다.

 

Linters / fixers

코드의 품질은 어떻게 유지하는가 ? PEP8 이나 PEP 257과 같은 스타일 가이드를 따르고 읽기 쉬운 일관된 방식으로 코드를 작성할 수 있다는 것을 알고 있을 것이다. 다른사람들이 코드를 어떻게 작성하고 프로젝트의 일부로 문서화하는지 관찰하고 그것으로 부터 배울 수 있다. 그리고 마지막으로 , linters를 사용할 수 있다.

 

린터(linters)란 무엇일까 ?

린터는 미리 정의된 규칙에 따라 코드의 스타일 오류나 프로그래밍 오류를 분석하여 코드 작성을 돕는 도구이다.

즉, 코드를 분석하여 구조적 오류나 구문 오류, 일관성 문제, PEP8과 같은 모범 사례, 코드 스타일 지침과의 호환성 부족등의 문제를 보고하는 프로그램이다.

가장 널리 쓰이는 린터는 Flake8, Pylint, Pychecher, Mypy, Pycodestyle이다.

https://flake8.pycqa.org/en/latest/

 

반면 픽서(fixers)는 이러한 문제를 해결하고 채택된 표준에 맞춰 코드를 포맷하는 데 도움이 되는 프로그램으로,

가장 널리 사용되는 픽서는 Black, YAPF, autopep8 이다.

https://pypi.org/project/black/

Client Challenge

 

대부분의 편집기와 IDE에는 린터를 지원하므로 코드를 작성하는 동안 백그라운드에서 실행할 수 있다.

린터를 사용하면, 오타, 잘못된 탭 및 들여쓰기 문제, 인수 개수가 잘못된 함수 호출, 스타일 불일치, 위험 코드 패턴 등 코드의 여러 문제 영역을 감지, 강조 표시 및 식별하고, 미리 정의된 사양에 따라 코드를 자동으로 포맷팅 할 수 있다.

파이썬은 이런 사용으로 코드의 품질을 높이고 프로그래머의 삶을 더 편리하게 만드는 것을 권장한다.

---

docstring에 접근하는 방법

파이썬의 __doc__ 속성을 활용하여 이를 수행할 수 있다.

함수/모듈/클래스/메서드 정의 뒤의 문자열 리터럴이 있는 경우 해당 객체의 __doc__ 속성과 연결되고,

이러한 속성은 객체에 대한 설명을 제공하게 된다.

def fun(a,b):
  """The summary line goes here.
  
  A more elaborate description of the function.
  
  Parameters:
  a : int (description)
  b : int (description)

  Return:
  int : Description of the return value.
  """
  return a*b

print(fun.__doc__)