의미있는 docstrings를 쓰는 방법?

StackOverflow https://stackoverflow.com/questions/601900

  •  03-07-2019
  •  | 
  •  

문제

당신의 의견으로는 의미있는 문서화는 무엇입니까? 거기에서 무엇을 설명 할 것으로 예상됩니까?

예를 들어이 파이썬 클래스를 고려하십시오 __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

이 의미가 있습니까? 모두가 알아야 할 좋은/나쁜 예를 게시하십시오 (그리고 일반적인 답변을 받아 들일 수 있습니다).

도움이 되었습니까?

해결책

나는 "방법의 서명에서 말할 수없는 모든 것"에 동의합니다. 또한 메소드/기능이 반환되는 것을 설명하는 것도 의미가있을 수 있습니다.

당신은 또한 사용하고 싶을 수도 있습니다 스핑크스 DocStrings 내부의 문서화 목적으로 (및 PrestucturedText Syntax). 그렇게하면 문서에 쉽게 포함시킬 수 있습니다. 예를 들어, 예를 들어 확인하십시오 repoze.bfg 이것을 광범위하게 사용합니다 (예제 파일, 문서 예제).

닥터 스트링에 넣을 수있는 또 다른 것도입니다 DocTests. 이것은 의미가있을 수 있습니다. 모듈 또는 클래스 DOCSTRING의 경우 사용 방법을 보여줄 수 있으며 동시에 테스트 할 수있는 방법을 보여줍니다.

다른 팁

에서 PEP 8:

좋은 문서 문자열 (일명 "docstrings")을 작성하기위한 규칙은 불멸화됩니다. PEP 257.

  • 모든 공개 모듈, 기능, 클래스 및 방법에 대한 문서를 작성하십시오. 비공개 방법에는 docstrings가 필요하지 않지만 방법이 무엇을하는지 설명하는 의견이 있어야합니다. 이 주석은 "DEF"라인에 나타나야합니다.
  • PEP 257 좋은 docstring 컨벤션을 설명합니다. 가장 중요한 것은 멀티 린 닥스트 링을 종료하는 "" "는 그 자체로는 선에 있어야하며 바람직하게는 빈 선에 앞서야한다는 점에 유의한다.
  • 하나의 라이너 docstrings의 경우, "" "를 같은 줄에 유지해도 괜찮습니다.

거기에 무엇을 해야하는지 :

방법의 서명에서 알 수없는 모든 것. 이 경우 유일한 유용한 것은 다음과 같습니다. displayName- 비어있는 경우 필드 이름으로 설정됩니다.

좋은 예를 보려면 Numpy의 Docstrings를 확인하십시오 (예 : http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

문서는 여러 섹션으로 나뉘어 다음과 같습니다.

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

내가 문서에 포함시키기 위해 생각할 수있는 가장 눈에 띄는 것들은 분명하지 않은 것들입니다. 일반적으로 여기에는 유형 정보 또는 기능 요구 사항이 포함됩니다. "파일과 같은 객체가 필요합니다". 경우에 따라 이것은 서명에서 명백 할 것입니다. 다른 경우에는 그렇지 않습니다.

당신이 당신의 docstrings에 넣을 수있는 또 다른 유용한 것은 doctest.

문서를 사용하여 기능이 수행하는 작업, 특히 코너 케이스 (일명 모서리 케이스)를 최대한 자세히 설명하고 싶습니다. 이상적으로는 함수를 사용하는 프로그래머는 소스 코드를 볼 필요가 없습니다. 실제로 다른 프로그래머가 소스 코드를보고 기능의 작동 방식에 대한 세부 사항을 파악해야 할 때마다 해당 세부 사항이 있었을 것입니다. 문서에 언급되었습니다. Freddy가 말했듯이, 메소드의 서명에 세부 사항을 추가하지 않는 것은 아마도 문학 문자열에 있지 않아야 할 것입니다.

일반적으로 기능을 시작할 때 Doc 문자열을 추가하는 목적은 기능, 수행의 작업, 반환의 작업 및 매개 변수에 대한 설명을 설명하는 것입니다. 필요한 경우 구현 세부 정보를 추가 할 수 있습니다. 심지어 미래 개발자를위한 코드를 작성한 저자에 대한 세부 정보를 추가 할 수 있습니다.

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top