31

あなたの意見では、意味のあるdocstringは何ですか? あなたはそこで何を説明することを期待していますか?

たとえば、この Python クラスの を考えてみましょう__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
    """

これは意味があると思いますか？あなたの良い/悪い例を投稿して、すべての人に知ってもらいます（そして、それが受け入れられるように一般的な回答を投稿してください）.

4

7 に答える 7

16

「メソッドのシグネチャから判断できないこと」に同意します。メソッド/関数が何を返すかを説明することも意味する場合があります。

docstring 内の文書化の目的でSphinx (および reStructuredText 構文)を使用することもできます。そうすれば、これをドキュメントに簡単に含めることができます。例については、これを広範囲に使用するrepoze.bfgなどをチェックしてください(例のファイル、ドキュメントの例)。

docstrings に入れることができるもう 1 つのものはdoctestsです。これは特に理にかなっているかもしれません。モジュールまたはクラスのdocstringの場合、その使用方法を示し、同時にこれをテスト可能にすることもできます。

于 2009-03-02T11:25:15.397 に答える
9

PEP 8から:

適切なドキュメント文字列 (別名「docstring」) を記述するための規則は、PEP 257で不滅です。

  • すべてのパブリック モジュール、関数、クラス、およびメソッドの docstring を記述します。Docstrings は非パブリック メソッドには必要ありませんが、メソッドの機能を説明するコメントが必要です。このコメントは、「def」行の後に表示する必要があります。
  • PEP 257は、優れた docstring 規則について説明しています。最も重要なことは、複数行の docstring を終了する """ は、それ自体で 1 行にある必要があり、できれば空白行が前にあることに注意してください。
  • 1 行の docstring の場合、終了の """ を同じ行に置いてもかまいません。
于 2009-03-02T12:51:32.177 に答える
7

良い例については、numpy のドキュメント文字列を確認してください (例: http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py )。

docstring はいくつかのセクションに分割され、次のようになります。

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
于 2011-01-14T10:56:25.690 に答える
6

そこに何をすべきか：

メソッドのシグネチャからは判断できないもの。この場合、唯一役立つのは次のとおりです。 displayName - 空の場合はフィールド名に設定されます。

于 2009-03-02T10:44:16.540 に答える
2

docstring に含めると私が考えることができる最も印象的なものは、明白ではないものです。通常、これにはタイプ情報または機能要件が含まれます。「ファイルのようなオブジェクトが必要です」。これは署名から明らかな場合もあれば、そうでない場合もあります。

docstring に入れることができるもう 1 つの便利なものは、doctest.

于 2009-03-02T12:34:34.123 に答える
1

ドキュメントを使用して、関数が何をするのか、特にコーナー ケース (別名エッジ ケース) での動作をできるだけ詳しく説明するのが好きです。理想的には、関数を使用するプログラマーはソース コードを確認する必要はありません。実際には、別のプログラマーが関数の動作の詳細を把握するためにソース コードを確認する必要がある場合は、その詳細を確認する必要があります。ドキュメントに記載されています。フレディが言ったように、メソッドの署名に詳細を追加しないものは、おそらくドキュメント文字列に含めるべきではありません。

于 2009-03-02T11:06:44.707 に答える