Como escrever docstrings significativas?

Question

O que, na sua opinião é uma docstring significativa? O que você espera para ser descrito lá?

Por exemplo, considere __init__ desta classe Python:

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
    """

Você acha que este significativo? Postar seus bons / maus exemplos para que todos saibam (e uma resposta geral para que possa ser aceite).

Answer 1

Concordo com "Qualquer coisa que você não pode dizer a partir da assinatura do método". Também pode significar para explicar o que é um método / função retorna.

Você também pode querer usar Esfinge (e sintaxe reStructuredText) para fins de documentação dentro de seus docstrings. Dessa forma, você pode incluir isso em sua documentação facilmente. Para um exemplo veja e.g. repoze.bfg que utiliza este extensivamente ( arquivo de exemplo , documentação exemplo ).

Outra coisa que se pode colocar em docstrings é também doctests . Isso pode fazer sentido esp. Para o módulo ou classe docstrings como você também pode mostrar dessa forma como usá-lo e ter esta testável, ao mesmo tempo.

Answer 2

A partir PEP 8 :

Convenções para cordas escrita boa documentação (A.K.A. "docstrings") são imortalizadas em PEP 257 .

• Escreva docstrings para todos os públicos módulos, funções, classes e métodos. Docstrings não são necessários para métodos não-públicos, mas você deve ter um comentário que descreva o que o método faz. este comentário deve aparecer após a linha "def".
• PEP 257 descreve boas convenções DocString. Note-se que o mais importante, o """ que termina a docstring várias linhas devem estar em um linha por si só, e de preferência precedido por uma linha em branco.
• Para um docstrings forro, está tudo bem para manter o fechamento """ na mesma linha.

Answer 3

O que deve ir lá:

Qualquer coisa que você não pode dizer a partir da assinatura do método. Neste caso, a única parte útil é:. DisplayName - se vazio será definido como nome de campo

Answer 4

Confira docstrings de numpy para bons exemplos (por exemplo http: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

Os docstrings são divididos em várias seções e olhar como este:

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

Answer 5

As coisas mais impressionantes que eu posso pensar para incluir em uma docstring são as coisas que não são óbvias. Normalmente, isso inclui informações sobre o tipo, ou requisitos de capacidade - por exemplo. "Requer um arquivo-como objeto". Em alguns casos, isso será evidente a partir da assinatura, não tão em outros casos.

Outra coisa útil que você pode colocar em seus docstrings é uma doctest.

Answer 6

Eu gosto de usar a documentação para descrever em detalhes, tanto quanto possível que a função faz, especialmente o comportamento em casos de canto (casos de ponta A.K.A.). Idealmente, um programador usando a função nunca deve ter que olhar para o código-fonte - na prática, isso significa que sempre que um outro programador tem de olhar para o código-fonte para descobrir alguns detalhes de como funciona a função, que detalham provavelmente deveria ter sido mencionado na documentação. Como disse Freddy, qualquer coisa que não adiciona qualquer detalhe para a assinatura do método provavelmente não deveria estar em uma string de documentação.

Answer 7

Geralmente finalidade de adicionar adicionando doc string no início da função é descrever a função, o que faz, o que ele iria voltar, e descrição sobre os parâmetros. Você pode adicionar detalhes de implementação, se necessário. Mesmo que você pode adicionar detalhes sobre o autor que escreveu o código para desenvolvedor futuro.