Docstrings vs Comments

Question

私は、docstringとpythonのコメントの違いより少し混乱しています。

私のクラスでは、先生が「デザインレシピ」と呼ばれるものを紹介しました。これは、生徒が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には、記述、Pythonシェルに関数を入力した場合の関数の例、 'タイプ契約'、入力するタイプとタイプを示すセクションの3つのものが含まれていなければなりません戻ります。

ここではこれがすべて完了しましたが、私たちの割り当てでは、トークン「＃」記号を使用して、機能の性質を説明するコメントも必要です。

私の質問は、すでに私の関数がdocstringのdescriptionセクションで何をするのかを説明していないのですか？読者に本質的に同じことを話している場合、コメントを追加する点は何ですか？

また、サイドノートでは、このコードを実際の投稿に一度正しく出力するために非常に恐ろしい時間があります。申し訳ありません。私は誰かがポストでコードを正しく書式設定する正しい方向に私を指すことができるとは思わない？

Answer 1

まず、投稿の書式設定には、投稿を入力するテキスト領域の上にヘルプオプションを使用できます。

コメントとドキュメント文字列について、ドキュメント文字列はメソッドの全体的な使い方と基本情報を説明するためのものです。一方、コメントはブロックや行に関する特定の情報を与えることを意図しています。#TODOは将来のやり方や変数の定義などを思い出させるために使用されます。ちなみに、IDLEでは、メソッドの名前の上にマウスを置くと、ドキュメントの文字列がツールチップとして表示されます。このページから引用

Answer 2

はhttp://www.pythonforbeginners.com/basics/python-docstrings/

Pythonドキュメント文字列（またはドキュメンテーション文字列）Pythonモジュール、関数、クラス、 及び方法と文書を関連付けるための便利な方法 を提供します。

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

コメントのように使用されるソースコードでは、 に特定のコードセグメントを記載しています。

従来のソースコードコメントとは異なり、docstringは をどのように記述しますか？

すべての機能がドキュメンテーション文字列に

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

ドキュメントストリングは、__ doc __属性でアクセスできます。

1. ドキュメンテーション文字列は、インラインコメントはアクセスできないようにプログラム（__doc__）を介してアクセスすることができます。
2. bpythonやIPythonのようなインタラクティブなヘルプシステムでは、開発中にドキュメンテーションを表示するためにdocstringを使用できます。あなたは毎回プログラムを訪れる必要はありません。

Answer 3

あなたの先生がプログラムをどのように設計するかのファンで表示されます。私はいつも重ならない二つの異なる読者のために書いとしてこれを取り組むと思います）

。

最初にドキュメントストリングがあります。これらは、必要なくしてコードを使用する人や、その動作を知りたい人のためのものです。ドキュメントストリングは実際のドキュメントに変換できます。公式のPythonドキュメンテーションを考えてみましょう - 各ライブラリで利用可能なものとその使用方法、実装の詳細はありません（使用に直接関係しない限り）

第2に、コード内のコメントがあります。これらは、コードを拡張したい人（一般的にあなた！）に何が起こっているのかを説明することです。これらは、実際にはコードではなく、使用法であるため、通常は文書化されません。プログラマーがいるように、良いコメント（またはその欠如）を作るために何がなされるかについて、今のところ多くの意見があります。コメントを追加するための私の個人的なルールは、説明することです：

• 必ず複雑なコードの部分。それ以外の場合は非論理的表示されることがありますを制御できませんコードの
• 回避策、（最適化が頭に浮かぶ）
• 私は最小
• にそれを維持しようとするものの、私は、同様TODOのに認めますよそのセクションでのパフォーマンスが後で重要になる場合は、より優れたパフォーマンス（より複雑な）オプションを選択できるように、よりシンプルなアルゴリズムを選択しました。

あなたは学術的な設定でコーディングしているようですあなたの講師は冗長になっています。設計レシピで行っていることをどのようにしているのかを説明するために、コードコメントを使用します。

Answer 4

私は、PEP8が言っていること、つまり純粋な概念について言及する価値はあると思います。良いドキュメンテーション文字列（別名、「ドキュメンテーション文字列」）を記述するための

ドキュメンテーション文字列

表記はPEP 257ですべてのパブリックモジュール、関数、クラス、メソッドの

書き込みドキュメンテーション文字列を不死化されています。非公開のメソッドには、ドキュメントストリングは必要ありませんが、メソッドが何をするかを説明するコメントが必要です。このコメントはdef行の後に現れます。

PEP 257は、良好なドキュメントストリングの慣例を説明しています。最も重要なのは、「」注意同じ行の「『』それは単独行にする必要があり、複数行のドキュメンテーション文字列を終了し、例えば：1つのライナードキュメンテーション文字列については

"""Return a foobang 

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

は、閉鎖を保管してください」。

コメント

ブロックは

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

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

インラインは控えめに

使用インラインコメントをコメント。

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

インラインコメントは必要ありません。

はこれをしないでください。

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

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

X = X + 1つの＃を国境の補償

参考

• https://www.python.org/dev/peps/pep-0008/#documentation-strings
• https://www.python.org/dev/peps/pep-0008/#inline-comments
• https://www.python.org/dev/peps/pep-0008/#block-comments
• https://www.python.org/dev/peps/pep-0257/