파이썬에서 함수를 주석 처리하는 올바른 방법은 무엇입니까?

파이썬에서 함수를 주석 처리하는 일반적으로 허용되는 방법이 있습니까? 다음이 허용됩니까?

#########################################################
# Create a new user
#########################################################
def add(self):

올바른 방법은 docstring을 제공하는 것입니다. 그렇게하면 help(add)의견을 뱉어냅니다.

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

그것은 주석을 열기위한 3 개의 큰 따옴표이고, 그것을 끝내기위한 또 다른 3 개의 큰 따옴표입니다. 유효한 Python 문자열을 사용할 수도 있습니다. 여러 줄일 필요는 없으며 큰 따옴표는 작은 따옴표로 대체 할 수 있습니다.

참조 : PEP 257

다른 사람들이 이미 작성한 것처럼 docstring을 사용하십시오.

당신은 한 단계를 이동하여 추가 할 수 있습니다 doctest가를 자동 스냅 당신의 기능의 테스트를 만들고, 당신의 문서화 문자열에.

docstring을 사용하십시오 :

모듈, 함수, 클래스 또는 메소드 정의에서 첫 번째 명령문으로 발생하는 문자열 리터럴입니다. 이러한 docstring은 __doc__해당 객체 의 특수 속성 이됩니다 .

모든 모듈에는 일반적으로 docstring이 있어야하며 모듈에서 내 보낸 모든 함수와 클래스에는 docstring도 있어야합니다. 공용 메소드 ( __init__생성자 포함 )에도 docstring이 있어야합니다. 패키지는 __init__.py패키지 디렉토리 에있는 파일 의 모듈 docstring에 문서화 될 수 있습니다 .

파이썬 코드의 다른 곳에서 발생하는 문자열 리터럴도 설명서 역할을 할 수 있습니다. 그것들은 파이썬 바이트 코드 컴파일러에 의해 인식되지 않으며 런타임 객체 속성 (즉 __doc__,에 할당되지 않음)으로 액세스 할 수 없지만 소프트웨어 도구에 의해 두 가지 유형의 추가 docstring이 추출 될 수 있습니다.

1. 모듈, 클래스 또는 __init__메서드 의 최상위 수준에서 간단한 할당 직후에 발생하는 문자열 리터럴을 "속성 문서 문자열"이라고합니다.
2. 다른 docstring 바로 다음에 나오는 문자열 리터럴을 "추가 docstrings"라고합니다.

속성 및 추가 docstring에 대한 자세한 설명 은 PEP 258 , "Docutils Design Specification" [2]를 참조하십시오.

좋은 의견 수렴의 원칙은 상당히 주관적이지만 다음과 같은 지침이 있습니다.

• 함수 주석은 구현이 아닌 함수 의 의도 를 설명해야합니다.
• 시스템 상태와 관련하여 함수가 수행하는 모든 가정을 설명하십시오. 전역 변수 (tsk, tsk)를 사용하는 경우 해당 변수를 나열하십시오.
• 과도한 ASCII 아트 를 조심하십시오 . 해시 문자열이 길면 주석을 쉽게 읽을 수 있지만 주석이 변경되면 처리하기가 어려울 수 있습니다.
• '자동 문서화'(예 : Python의 docstring, Perl의 POD 및 Java의 Javadoc)를 제공하는 언어 기능을 활용하십시오.

Python 코드에서 docstring 사용에 대해 읽으십시오 .

파이썬 docstring 규칙에 따라 :

함수 또는 메소드의 docstring은 그 동작을 요약하고 인수, 반환 값, 부작용, 발생 된 예외 및 호출 가능시기에 대한 제한 사항 (해당되는 경우 모두)을 문서화해야합니다. 선택적 인수가 표시되어야합니다. 키워드 인수가 인터페이스의 일부인지 여부를 문서화해야합니다.

황금률은 없지만, 팀의 다른 개발자 (있는 경우) 나 6 개월 후 다시 돌아올 때 자신에게 의미가있는 의견을 제공하십시오.

Sphinx 와 같은 문서화 도구와 통합되는 문서화 실습을 원합니다 .

첫 번째 단계는 다음을 사용하는 것입니다 docstring.

def add(self):
 """ Method which adds stuff
 """

"docstring 사용"이라고 말하는 것보다 한 걸음 더 나아갈 것입니다. pydoc 또는 epydoc (pyparsing에서 epydoc을 사용함)과 같은 문서 생성 도구를 선택하고 해당 도구가 인식하는 마크 업 구문을 사용하십시오. 개발하는 동안 해당 도구를 자주 실행하여 문서의 허점을 식별하십시오. 실제로 클래스 를 구현 하기 전에 클래스 멤버에 대한 docstring을 작성하는 것이 도움이 될 수도 있습니다 .

docstrings를 사용하십시오 .

이것은 함수 설명 주석에 대한 PyCharm 의 기본 제안 규칙입니다 .

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

나는 이것이 주석이 아니라 대부분의 (모든?) 답변이 제안하는 docstring에 동의하지만 numpydoc (docstring 스타일 가이드) 을 추가하고 싶습니다 .

이렇게하면 (1) 자동으로 문서를 생성하고 (2) 사람들이이를 인식하고 코드를 쉽게 읽을 수 있습니다.

세 따옴표를 사용하여 할 수 있습니다.

작은 따옴표를 사용할 수 있습니다 :

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

또는 큰 따옴표 :

def myfunction(para1,para2):
  """
  The stuff inside the function
  """