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

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

#########################################################
# 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을 작성하는 것이 도움이 될 수도 있습니다 .