web-dev-qa-db-ja.com

Docstrings vsコメント

Pythonでのdocstringとコメントの違いについて少し混乱しています。

私のクラスでは、先生が「デザインレシピ」と呼ばれるものを紹介しました。これは、Pythonでのコーディングをよりよく計画し整理するのに役立つと思われる一連の手順です。私が理解していることから、以下は私たちが従うステップの例です-これは設計レシピと呼ばれます（引用の中のもの）：

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):

    ''' (float, float, float, float, float) -> float

    Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
    calculates their respective weight contributions and sums these 
    contributions to deliver your overall term mark out of a maximum of 55 (This
    is because the exam mark is not taken account of in this function)

    >>>term_work_mark(5, 5, 5, 5, 5)
    11.8
    >>>term_work_mark(0, 0, 0, 0, 0)
    0.0
    '''

    a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
    a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
    a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
    ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
    mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
    return (a0_component + a1_component + a2_component + ex_component + 
            mid_component)

私が理解している限り、これは基本的にdocstringであり、このバージョンのdocstringでは、3つのことを含める必要があります。説明、pythonシェル、および「タイプコントラクト」、入力したタイプおよび関数が返すタイプを示すセクション。

これですべてうまくいきましたが、割り当てには、トークン「＃」記号を使用して、関数の性質を説明するコメントも必要です。

だから、私の質問は、docstringのdescriptionセクションで私の関数が何をするのかをすでに説明していないのですか？基本的に読者にまったく同じことを伝える場合、コメントを追加する意味は何ですか？

pythoncommentsdocstring
29
Jeremy

先生はプログラムの設計方法のファンのようです;）

これは、常に重複するとは限らない2人の異なるオーディエンス向けに書くこととして取り組んでいます。

最初にdocstringがあります。これらは、コードがどのように機能するかを必要としない、または知りたくないときにコードを使用しようとしている人向けです。 Docstringsは、実際のドキュメントに変換できます。公式Pythonドキュメンテーション-各ライブラリで利用可能なものとその使用方法、実装の詳細はありません（それらが使用に直接関連していない限り）

次に、コード内のコメントがあります。これらは、コードを拡張したい人々（一般的にあなた！）に何が起こっているかを説明するためのものです。これらは実際には使用法ではなくコード自体に関するものであるため、通常はドキュメントに変換されません。現在、プログラマーと同じくらい多くの意見が、良いコメント（またはその欠如）をもたらすものについてあります。コメントを追加するための私の個人的な経験則は説明することです：

  • 必然的に複雑なコードの部分。 （最適化が頭に浮かぶ）
  • あなたが制御できないコードの回避策は、そうでなければ非論理的に見えるかもしれません
  • TODOも認めますが、最小限に抑えるようにしています
  • 後でそのセクションのパフォーマンスが重要になった場合に、よりパフォーマンスの高い（ただしより複雑な）オプションを使用できる、より単純なアルゴリズムを選択した場合

あなたはアカデミックな環境でコーディングしており、講師が冗長になりそうなように聞こえるので、私はそれをそのまま使いましょう。コードコメントを使用して、デザインレシピで自分が言っていることをどのように行っているかを説明します。

34
dejester

まず、投稿をフォーマットするには、投稿を入力するテキスト領域の上にあるヘルプオプションを使用できます。

また、コメントとドキュメント文字列については、メソッドの全体的な使用法と基本情報を説明するドキュメント文字列があります。一方、コメントはブロックまたは行に関する特定の情報を提供するためのものであり、＃TODOは、将来何をしたいか、変数の定義などを思い出させるために使用されます。ところで、IDLEでは、メソッド名にカーソルを合わせると、ドキュメント文字列がツールヒントとして表示されます。

4
Reza Shayestehpour

このページから引用 http://www.pythonforbeginners.com/basics/python-docstrings/

Pythonドキュメント文字列（またはdocstring）は、ドキュメントをPythonモジュール、関数、クラス、およびメソッドに関連付ける便利な方法を提供します。

オブジェクトのドキュメントは、オブジェクトの定義の最初のステートメントとして文字列定数を含めることで定義されます。

コメントのように、特定のコードセグメントを文書化するために使用されるソースコードで指定されます。

従来のソースコードのコメントとは異なり、docstringは、方法ではなく、関数の動作を説明する必要があります。

すべての関数にはdocstringが必要です

これにより、プログラムはこれらのコメントを実行時に、たとえば対話型ヘルプシステムとして、またはメタデータとして検査できます。

文書文字列には、オブジェクトの__doc__属性でアクセスできます。

  1. Docstringsはプログラム（__doc__）インラインコメントとしてアクセスできない場合。
  2. BpythonやIPythonなどの対話型ヘルプシステムは、開発中にdocstringを使用してドキュメントを表示できます。毎回プログラムを訪れる必要がないように。
3
thefourtheye

PEP8が言っていること、つまり純粋な概念に言及する価値があると思います。

Docstrings

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

すべてのパブリックモジュール、関数、クラス、およびメソッドのドキュメント文字列を記述します。パブリック文字列は非パブリックメソッドには必要ありませんが、メソッドの機能を説明するコメントが必要です。このコメントはdef行の後に表示されます。

PEP 257では、適切なdocstring規則について説明しています。最も重要なことに、複数行のdocstringを終了する "" "は、単独で行上にある必要があります。例えば：

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

1つのライナーdocstringの場合、閉じている「」を同じ行に置いてください。

コメント

ブロックコメント

一般的に、それに続くいくつかの（またはすべての）コードに適用され、そのコードと同じレベルにインデントされます。ブロックコメントの各行は、＃と1つのスペースで始まります（コメント内のテキストがインデントされていない場合）。

ブロックコメント内の段落は、単一の＃を含む行で区切られます。

インラインコメント

インラインコメントは控えめに使用してください。

インラインコメントは、ステートメントと同じ行のコメントです。インラインコメントは、ステートメントから少なくとも2つのスペースで区切る必要があります。 ＃と1つのスペースで始まる必要があります。

インラインコメントは不要であり、実際に明らかなことを述べている場合、実際には注意をそらします。

これをしないでください：

x = x + 1＃インクリメントx

しかし、時々これは便利です：

x = x + 1＃境界の補正

参照

3
ivanleoncz