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

Question

在 Python 中是否有一种普遍接受的方法来注释函数？以下是否可以接受？

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

原文由 ensnare 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

正确的做法是提供文档字符串。这样， help(add) 也会吐出你的评论。

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

这是三个双引号打开评论和另外三个双引号结束它。您还可以使用任何有效的 Python 字符串。它不需要是多行的，双引号可以用单引号代替。

参见： PEP 257

原文由 Chinmay Kanchi 发布，翻译遵循 CC BY-SA 3.0 许可协议

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

原文由 Shwetabh Shekhar 发布，翻译遵循 CC BY-SA 4.0 许可协议