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

使用docstring，正如其他人已经写过的那样。

您甚至可以更进一步，在文档字符串中添加doctest，快速自动测试您的功能。

Answer 3

使用docstring：

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

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

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


在模块，类或__init__方法的顶层进行简单赋值后立即出现的字符串文字称为“属性docstrings”。

在另一个docstring之后立即发生的字符串文字被称为“附加文档字符串”。

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

Answer 4

哦，小男孩！考虑打开一罐蠕虫：）

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

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

Answer 5

了解在python代码中使用docstrings。

根据Python Docstring约定：

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

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

Answer 6

我会选择与文档工具集成的文档练习，例如 Sphinx 。

第一步是使用docstring：

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

Answer 7

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

Answer 8

虽然我同意这不是注释，而是大多数（所有？）答案都建议的文档字符串，但我想添加 numpydoc （文档字符串样式指南）：https://github.com/numpy/numpy/blob/254c50af3a52c8b1444e46857e9ec59fcb212a41/doc/HOWTO_DOCUMENT.rst.txt < / p>

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

Answer 9

使用docstrings。
这是PyCharm中用于函数描述注释的内置建议约定。

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

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

Answer 10

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

您可以使用单引号：

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

或双引号：

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

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

10 个答案: