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

Question

在Python中，有没有一种大家都认可的方式来给函数写注释？下面这种写法可以吗？

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

Answer 1

使用文档字符串，就像其他人已经提到的那样。

你甚至可以更进一步，在你的文档字符串中添加一个 doctest，这样就能轻松地对你的函数进行自动测试。

Answer 2

使用 文档字符串。

这是在 PyCharm 中推荐的写法，用来描述函数的文档字符串注释：

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

    :param p1: describe about parameter p1
    :param p2: describe about parameter p2
    :param p3: describe about parameter p3
    :return: describe what it returns
    """ 
    pass

Answer 3

正确的做法是提供一个文档字符串。这样，当你输入 help(add) 时，它也会显示你的注释。

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

这里用三个双引号来开始注释，再用三个双引号来结束。你也可以使用任何有效的Python字符串。注释不一定要多行，双引号也可以换成单引号。

详情请见：PEP 257