Pythonで関数にコメントする適切な方法は何ですか？

Pythonで関数にコメントする一般的に受け入れられている方法はありますか？以下は許容されますか？

#########################################################
# Create a new user
#########################################################
def add(self):

それを行う正しい方法は、docstringを提供することです。そうhelp(add)すれば、コメントも吐き出されます。

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

これは、コメントを開くための3つの二重引用符と、コメントを終了するための3つの二重引用符です。有効なPython文字列を使用することもできます。複数行である必要はなく、二重引用符を単一引用符で置き換えることができます。

参照：PEP 257

他の人がすでに書いているように、docstringを使用してください。

さらに一歩進んで、doctestにdoctestを追加して、関数の自動テストを簡単にすることもできます。

docstringを使用します。

モジュール、関数、クラス、またはメソッド定義の最初のステートメントとして出現する文字列リテラル。このようなdocstringは、__doc__そのオブジェクトの特別な属性になります。

すべてのモジュールには通常docstringが必要であり、モジュールによってエクスポートされるすべての関数とクラスにもdocstringが必要です。パブリックメソッド（__init__コンストラクターを含む）にもdocstringが必要です。パッケージは__init__.py、パッケージディレクトリ内のファイルのモジュールdocstringに文書化できます。

Pythonコードの他の場所にある文字列リテラルも、ドキュメントとして機能する場合があります。これらはPythonバイトコードコンパイラでは認識されず、ランタイムオブジェクト属性としてアクセスできません（つまり、に割り当てられていません__doc__）。ただし、ソフトウェアツールによって2種類の追加のdocstringが抽出される場合があります。

1. モジュール、クラス、または__init__メソッドの最上位の単純な割り当ての直後に発生する文字列リテラルは、「属性docstrings」と呼ばれます。
2. 別のdocstringの直後に出現する文字列リテラルは、「追加のdocstrings」と呼ばれます。

属性と追加のdocstringの詳細な説明については、PEP 258「Docutils Design Specification」[2]を参照してください...

良いコメントの原則はかなり主観的ですが、ここにいくつかのガイドラインがあります：

• 関数のコメントは、実装ではなく関数の意図を説明する必要があります
• 関数がシステム状態に関して行うすべての仮定の概要を説明します。グローバル変数（tsk、tsk）を使用する場合は、それらをリストします。
• 過剰なASCIIアートに注意してください。ハッシュの文字列が長いと、コメントが読みやすくなりますが、コメントが変更されたときに対処するのが面倒です。
• 「自動ドキュメンテーション」を提供する言語機能、つまり、Pythonのdocstring、PerlのPOD、JavaのJavadocを利用する

Pythonコードでのdocstringsの使用について読んでください。

Python docstring規約に従って：

関数またはメソッドのdocstringは、その動作を要約し、その引数、戻り値、副作用、発生した例外、およびいつ呼び出すことができるかの制限（該当する場合はすべて）を文書化する必要があります。オプションの引数を指定する必要があります。キーワード引数がインターフェースの一部であるかどうかを文書化する必要があります。

黄金律はありませんが、チームの他の開発者（もしあれば）や、6か月後に戻ってきたときに自分自身に何かを意味するコメントを提供します。

Sphinxなどのドキュメンテーションツールと統合するドキュメンテーションプラクティスに行きます。

最初のステップは、使用することですdocstring：

def add(self):
 """ Method which adds stuff
 """

「docstringを使用してください」と言うだけではなく、さらに一歩進んでいきます。pydocやepydocなどのドキュメント生成ツール（私はpyparsingでepydocを使用しています）を選択し、そのツールで認識されるマークアップ構文を使用します。開発中にツールを頻繁に実行して、ドキュメントの穴を特定します。実際、クラスを実装する前に、クラスのメンバーのdocstringを作成することでメリットを得ることもできます。

docstringsを使用します。

これは、PyCharmに組み込まれている、関数の説明コメントに関する推奨される規則です。

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

これはコメントではないことに同意しますが、ほとんど（すべて？）の回答が示唆するようにdocstringですが、numpydoc（docstringスタイルガイド）を追加したいと思います。

このようにすると、（1）ドキュメントを自動的に生成し、（2）人々がこれを認識して、コードを読みやすくなります。

それには、3つの引用符を使用できます。

一重引用符を使用できます。

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

または二重引用符：

def myfunction(para1,para2):
  """
  The stuff inside the function
  """