在python中评论函数的正确方法是什么？
有一个普遍接受的方式来做到这一点？ 这是可以接受的：
######################################################### # Create a new user ######################################################### def add(self): 正确的方法是提供一个文档string。 这样， help(add)也会吐出你的评论。
def add(self): """Create a new user. Line 2 of comment... And so on... """
这是三个双引号打开评论和另外三个双引号来结束它。 你也可以使用任何有效的Pythonstring。 它不需要多行，双引号可以用单引号replace。
见： PEP 257
像其他人已经写过的那样使用文档string。
你甚至可以更进一步，将doctest添加到你的文档string，使你的函数自动testing。
使用文档string ：
作为模块，函数，类或方法定义中的第一条语句出现的string文字。 这样的docstring成为该对象的
__doc__特殊属性。所有模块通常应该有文档，所有由模块导出的函数和类也应该有文档。 公共方法（包括
__init__构造函数）也应该有docstrings。 软件包可能logging在软件包目录中的__init__.py文件的模块文档string中。在Python代码中出现的string文字也可以作为文档。 它们不被Python字节码编译器识别，并且不能作为运行时对象属性（即未分配给
__doc__）访问，但可以通过软件工具提取两种types的额外文档string：
- 在模块，类或
__init__方法的顶级简单赋值之后立即出现的string文字被称为“属性文档string”。- 在另一个文档string之后立即出现的string文字称为“其他文档string”。
请参阅PEP 258 ，“Docutilsdevise规范” [2] ，了解属性和附加文档的详细说明…
好家伙！ 考虑一个蠕虫打开:)
良好的评论原则是相当主观的，但这里有一些指导：
- 函数注释应该描述函数的意图 ，而不是实现
- 概述你的函数关于系统状态的任何假设。 如果它使用任何全局variables（tsk，tsk），请列出这些variables。
- 注意过度的ASCII艺术。 长长的哈希串可能似乎使评论更容易阅读，但他们可能是讨厌的时候处理意见改变
- 利用提供“自动文档”的语言function，即Python中的docstrings，Perl中的POD，Java中的Javadoc
阅读有关在Python代码中使用文档string的信息 。
根据Python Docstring约定：
函数或方法的文档string应总结其行为并logging其参数，返回值，副作用，引发的exception，以及何时可以调用的限制（如果适用）。 可选的参数应该被指出。 应该logging关键字参数是否是界面的一部分。
没有黄金法则，而是给你的团队中的其他开发人员（如果有的话）提供意见，甚至在你回到路上的六个月之后给你自己提供意见。
我会去做一个与文档工具（如Sphinx）集成的文档练习。
第一步是使用docstring ：
def add(self): """ Method which adds stuff """
我会更进一步，只是说“使用文档string”。 select文档生成工具，如pydoc或epydoc（我在pyparsing中使用epydoc），并使用该工具识别的标记语法。 在开发过程中经常运行该工具，以查明文档中的漏洞。 事实上， 在实施课程之前 ，您甚至可以从为class级成员编写文档中受益。
