用Python注释函数的正确方法是什么？

有没有一种普遍接受的方法来注释Python中的函数？可以接受以下内容吗？

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

正确的方法是提供文档字符串。这样，help(add)还将吐出您的评论。

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

那是三个双引号来打开评论，另外三个双引号来结束它。您也可以使用任何有效的Python字符串。它不必是多行的，双引号可以替换为单引号。

请参阅：PEP 257

使用其他人已经写过的文档字符串。

您甚至可以更进一步，并在文档字符串中添加一个文档测试，从而使对功能的自动测试变得轻而易举。

使用文档字符串：

作为模块，函数，类或方法定义中的第一条语句出现的字符串文字。这样的文档字符串成为该__doc__对象的特殊属性。

通常，所有模块都应具有文档字符串，并且模块导出的所有函数和类也应具有文档字符串。公共方法（包括__init__构造函数）也应具有文档字符串。包可以记录在__init__.py包目录中文件的模块文档字符串中。

Python代码其他地方出现的字符串文字也可以用作文档。它们无法被Python字节码编译器识别，并且不能作为运行时对象属性（即未分配给__doc__）进行访问，但是软件工具可以提取两种类型的额外docstring：

1. 在模块，类或__init__方法的顶级进行简单分配后立即出现的字符串文字称为“属性文档字符串”。
2. 在另一个文档字符串之后立即出现的字符串文字称为“其他文档字符串”。

有关属性和附加文档字符串的详细说明，请参见PEP 258，“ Docutils设计规范” [2]。

良好评论的原则是相当主观的，但是这里有一些准则：

• 函数注释应描述函数的意图，而不是实现
• 概述您的功能对系统状态所做的任何假设。如果它使用任何全局变量（tsk，tsk），请列出它们。
• 提防过多的ASCII艺术。散列很长的字符串似乎使注释更易于阅读，但是当注释更改时，它们可能很烦人
• 利用提供“自动文档”的语言功能，例如，Python中的文档字符串，Perl中的POD和Java中的Javadoc

阅读有关在Python代码中使用文档字符串的信息。

按照Python docstring约定：

函数或方法的文档字符串应总结其行为，并记录其参数，返回值，副作用，引发的异常以及何时可以调用它的限制（所有这些均适用）。应该指出可选参数。应该记录关键字参数是否是接口的一部分。

没有黄金法则，而是提供评论，这对于您团队中的其他开发人员（如果有的话）或对您自己意味着意义的评论，如果您在六个月后再回到它的话。

我会去进行与Sphinx等文档工具集成的文档实践。

第一步是使用docstring：

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

除了说“使用文档字符串”外，我将走得更远。选择一个文档生成工具，例如pydoc或epydoc（我在pyparsing中使用epydoc），然后使用该工具可以识别的标记语法。在进行开发时经常运行该工具，以发现文档中的漏洞。实际上，您甚至可以从实现类之前为类的成员编写文档字符串中受益。

用 docstrings。

这是PyCharm中针对功能描述注释的内置建议约定：

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

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

虽然我同意这不应该是评论，但应该是大多数（所有？）答案都建议的文档字符串，但我想添加numpydoc（文档字符串样式指南）。

如果这样做，您可以（1）自动生成文档，并且（2）人们可以识别出这一点，并且可以更轻松地读取代码。

您可以使用三个引号来做到这一点。

您可以使用单引号：

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

或双引号：

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