意味のあるドキュメント文字列を書く方法は？

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

  •  03-07-2019
  •  | 
  •  

質問

あなたの意見では、意味のある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
    """

これには意味がありますか？知っておくべきすべての良い例と悪い例を投稿してください（受け入れられるように一般的な回答を記入してください）。

役に立ちましたか？

解決

「メソッドの署名から判断できないもの」に同意します。メソッド/関数が返すものを説明することも意味します。

ドキュメンテーション文字列内でのドキュメント化のために、 Sphinx （およびreStructuredText構文）を使用することもできます。そうすれば、これをドキュメントに簡単に含めることができます。例については、例えば repoze.bfg これを広範囲に使用しています（サンプルファイル、ドキュメントの例）。

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

他のヒント

PEP 8 から：

  

適切なドキュメント文字列を記述するための規約（別名：   ＆quot; docstrings＆quot;）は PEP 257 で不滅です。

     
      
  • すべてのパブリックモジュール、関数、クラス、およびメソッドのドキュメント文字列を作成します。非パブリックメソッドにはドキュメント文字列は必要ありませんが、   メソッドの実行内容を説明するコメントが必要です。この   コメントは＆quot; def＆quot;の後に表示されます行。
    •   
  • PEP 257 では、適切なdocstring規則について説明しています。最も重要なのは、＆quot;＆quot;＆quot;複数行のdocstringを終了するものは、   行単独で、できれば前に空白行を追加します。
    •   
  • 1つのライナーdocstringの場合、閉じている＆quot;＆quot;＆quot;をそのままにしておいてもかまいません。同じ行に。
    •   

そこに行くべきもの：

メソッドの署名から判断できないもの。この場合、唯一役立つビットは：displayName-空の場合はフィールド名に設定されます。

良い例については、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

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

docstringに追加できるもう1つの便利な機能は、 doctest です。

ドキュメントを使用して、機能の動作、特にコーナーケース（エッジケース）の動作を可能な限り詳細に説明するのが好きです。理想的には、関数を使用するプログラマーはソースコードを見る必要はありません-実際には、別のプログラマーがソースコードを見て関数の動作の詳細を把握する必要があるときはいつでも、その詳細はおそらくドキュメントに記載されています。 Freddyが言ったように、メソッドのシグネチャに詳細を追加しないものは、おそらくドキュメントの文字列に含めるべきではありません。

関数の開始時に追加のdoc文字列を追加する一般的な目的は、関数、その機能、返される内容、およびパラメーターに関する説明を記述することです。必要に応じて、実装の詳細を追加できます。将来の開発者向けにコードを書いた著者に関する詳細を追加することもできます。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top