在python中评论函数的正确方法是什么？

Question

是否有一种普遍接受的方式来做到这一点？这是可以接受的:

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

Answer 1

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

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

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

见:PEP 257

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

使用docstring,正如其他人已经写过的那样.

您甚至可以更进一步,在文档字符串中添加doctest,从而快速自动测试您的函数.

Answer 4

使用docstring:

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

所有模块通常都应该有文档字符串,模块导出的所有函数和类也应该有文档字符串.公共方法(包括__init__构造函数)也应该有docstrings.包可以记录在__init__.py包目录中的文件的模块docstring中.

Python代码中其他地方出现的字符串文字也可以作为文档.它们不被Python字节码编译器识别,并且不能作为运行时对象属性(即未分配给__doc__)来访问,但软件工具可以提取两种类型的额外文档字符串:

1. 在模块,类或__init__方法的顶层进行简单赋值后立即出现的字符串文字称为"属性docstrings".
2. 紧接在另一个docstring之后发生的字符串文字称为"附加文档字符串".

有关属性和其他文档字符串的详细说明,请参阅PEP 258,"Docutils设计规范" [2].

Answer 5

好家伙!考虑一罐蠕虫打开:)

良好评论的原则是相当主观的,但这里有一些指导:

• 函数注释应该描述函数的意图,而不是实现
• 概述您的功能对系统状态的任何假设.如果它使用任何全局变量(tsk,tsk),请列出这些变量.
• 注意过多的ASCII艺术.使用长字符串哈希似乎可以使注释更容易阅读,但是当注释更改时,它们可能会很烦人
• 利用提供"自动文档"的语言功能,即Python中的文档字符串,Perl中的POD,Java中的Javadoc

Answer 6

阅读有关在python代码中使用docstrings的内容.

根据Python Docstring约定:

函数或方法的docstring应该总结其行为并记录其参数,返回值,副作用,引发的异常以及何时可以调用它们的限制(如果适用,则全部).应指出可选参数.应记录关键字参数是否是接口的一部分.

没有黄金法则,而是提供对你团队中的其他开发人员(如果你有的话)有意义的评论,或者甚至在你六个月后再回到它自己时.

Answer 7

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

第一步是使用docstring：

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