파이썬에서 docstring을 작성하는 몇 가지 다른 스타일을 보았습니다. 공식 또는 "합의 된"스타일이 있습니까?

체재

파이썬 docstring은 다른 게시물이 보여준 것처럼 여러 형식으로 작성 될 수 있습니다. 그러나 기본 Sphinx docstring 형식은 언급되지 않았으며 reStructuredText (reST)를 기반으로 합니다. 이 블로그 게시물 에서 주요 형식에 대한 정보를 얻을 수 있습니다 .

reST는 PEP 287에서 권장합니다.

docstring에 사용되는 주요 형식은 다음과 같습니다.

-Epytext

역사적으로 스타일과 같은 javadoc 이 널리 사용 되었기 때문에 문서를 생성하기 위해 Epydoc (호출 Epytext형식) 의 기반으로 사용되었습니다 .

예:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- 쉬다

요즘 가장 널리 사용되는 형식은 문서를 생성하기 위해 Sphinx 에서 사용하는 reST ( reStructuredText ) 형식입니다 . 참고 : JetBrains PyCharm에서 기본적으로 사용됩니다 (메소드를 정의하고 Enter 키를 누른 후 삼중 따옴표를 입력하십시오). 기본적으로 Pyment에서 출력 형식으로 사용됩니다.

예:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

-구글

Google에는 자주 사용되는 자체 형식 이 있습니다. 또한 스핑크스 (예 : Napoleon 플러그인 사용 ) 로 해석 할 수 있습니다 .

예:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

심지어 더 많은 예제

-누 피독

Numpy 는 Google 형식에 따라 Sphinx에서 사용할 수있는 고유 한 numpydoc 을 따르는 것이 좋습니다 .

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

변환 / 생성

Pyment 와 같은 도구를 사용하여 문서화 문자열을 아직 문서화되지 않은 Python 프로젝트로 자동 생성하거나 기존의 문서화 문자열 (여러 형식을 혼합 할 수 있음)을 형식에서 다른 형식으로 변환 할 수 있습니다.

참고 : 예제는 Pyment 문서 에서 가져 왔습니다.

구글 스타일 가이드는 훌륭한 파이썬 스타일 가이드가 포함되어 있습니다. PEP-257보다 더 나은 지침을 제공하는 읽을 수있는 docstring 구문에 대한 규칙 이 포함되어 있습니다 . 예를 들면 다음과 같습니다.

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

이 Sphinx 문서 튜토리얼에 설명 된대로 인수에 유형 정보도 포함하도록 이것을 확장하고 싶습니다 . 예를 들면 다음과 같습니다.

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

문서 문자열 규칙은 PEP-257에 있으며 PEP-8보다 훨씬 자세합니다.

그러나 docstring은 다른 코드 영역보다 훨씬 개인적인 것으로 보입니다. 다른 프로젝트에는 자체 표준이 있습니다.

나는 항상 docstring을 포함하는 경향이있다. 그것들은 함수를 사용하는 방법과 그것이 매우 빠르게하는 것을 보여주기 때문이다.

나는 끈의 길이에 관계없이 일을 일관성있게 유지하는 것을 선호합니다. 들여 쓰기와 간격이 일관 적 인 경우 코드 모양을 좋아합니다. 즉, 나는 다음을 사용합니다.

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

위에:

def sq(n):
    """Returns the square of n."""
    return n * n

그리고 더 긴 docstring에서 첫 줄에 주석을 남기는 경향이 있습니다.

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

의미 나는 이렇게 시작되는 docstrings가 지저분하다는 것을 알았습니다.

def sq(n):
    """Return the squared result. 
    ...

아무 것도 언급하지 않았 으므로 Numpy Docstring Standard를 사용할 수도 있습니다 . 과학계에서 널리 사용됩니다.

• 포맷 사양 와 NumPy와 함께에서 예
• 스핑크스 확장 기능을 사용하여 렌더링 할 수 있습니다 : numpydoc
• 그리고 렌더링 된 docstring이 얼마나 아름답게 보일 수 있는지에 대한 예는 다음과 같습니다. http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

@Nathan의 답변으로 권장되는 Google 스타일 docstring을 구문 분석하기위한 Napolean 스핑크스 확장은 Numpy 스타일 docstring을 지원하며 두 가지를 짧게 비교 합니다.

마지막 예제는 다음과 같습니다.

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

PEP-8 은 공식적인 파이썬 코딩 표준입니다. 여기에는 docstring에 대한 섹션이 포함되어 있으며, 이는 docstring에 대한 완전한 사양 인 PEP-257 을 나타냅니다 .

파이썬입니다. 무슨 일이든 상관 없습니다 . 문서 를 게시 하는 방법을 고려하십시오 . 소스 코드를 읽는 사람을 제외하고는 문서 스트링이 보이지 않습니다.

사람들은 웹에서 문서를 탐색하고 검색하는 것을 정말로 좋아합니다. 이를 위해서는 문서 도구 Sphinx를 사용하십시오 . 파이썬 프로젝트를 문서화하기위한 사실상의 표준입니다. 제품은 아름답습니다-https: //python-guide.readthedocs.org/en/latest/를보십시오 . Read the Docs 웹 사이트에서 문서를 무료로 호스팅합니다.

Vladimir Keleshev의 pep257 Python 프로그램을 사용하여 매개 변수, 반환 등을 설명하기 위해 PEP-257 및 Numpy Docstring Standard 와 비교하여 문서 문자열을 확인 하는 것이 좋습니다 .

pep257은 표준에서 발산되는 차이를보고하며 pylint 및 pep8과 같습니다.