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

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

#########################################################
# Create a new user
#########################################################
def add(self):
266807 次浏览
小开

阅读有关在Python代码中使用文档字符串的知识。

根据Python 有约定:

函数或方法的文档字符串应该总结它的行为，并记录它的参数、返回值、副作用、引发的异常以及何时可以调用它的限制(如果适用，所有这些都要记录)。应指明可选参数。关键字参数是否属于接口的一部分应该记录下来。

这里没有黄金法则，而是提供对团队中其他开发者(如果你有的话)有意义的评论，甚至是当你在6个月后再回过头来看它时对你自己也有意义的评论。

小开
最佳答案

正确的方法是提供一个文档字符串。这样，help(add)也会吐出你的注释。

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

这是三个双引号来开始注释，另外三个双引号来结束注释。你也可以使用任何有效的Python字符串。它不需要多行，双引号可以被单引号取代。

看:PEP 257

小开

我会选择与诸如Sphinx之类的文档工具集成的文档实践。

第一步是使用docstring:

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

使用所以:

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

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

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

  1. 在模块、类或__init__方法的顶层进行简单赋值后立即出现的字符串字面量称为“attribute docstrings”。
  2. 紧接在另一个文档字符串之后出现的字符串字面值称为“附加文档字符串”。

请参阅PEP 258， "Docutils设计规范" [２]，获取属性和其他文档字符串的详细描述…

小开

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

你甚至可以更进一步，在你的文档字符串中添加doctest，使函数的自动测试变得简单。

小开

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

  • 函数注释应该描述函数的意图，而不是函数的实现
  • 概述你的函数对系统状态所做的任何假设。如果它使用任何全局变量(啧啧)，列出它们。
  • 注意过量的ASCII艺术。使用长哈希字符串似乎使注释更容易阅读，但当注释发生变化时，处理它们可能会很麻烦
  • 充分利用提供“自动文档”的语言特性，即Python中的文档字符串、Perl中的POD和Java中的Javadoc
小开

我会更进一步，而不仅仅是说“使用文档字符串”。选择一个文档生成工具，如pydoc或epydoc(我在pyparsing中使用epydoc)，并使用该工具识别的标记语法。在开发过程中经常运行该工具，以识别文档中的漏洞。事实上，你甚至可以从为实现类的类之前的成员编写文档字符串中受益。

小开

虽然我同意这不应该是注释，而是大多数(所有?)答案所建议的文档字符串，但我想添加numpydoc(文档字符串风格指南)。

如果你这样做，你可以(1)自动生成文档，(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
小开

你可以用三个引号来做这件事。

你可以使用单引号:

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

或者双引号:

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

正确的方法如下:

def search_phone_state(phone_number_start,state,dataframe_path,separator):
"""
returns records whose phone numbers begin with a phone_number_start and are from state
"""
dataframe = pd.read_csv(filepath_or_buffer=dataframe_path, sep=separator, header=0)
return dataframe[(pd.Series(dataframe["Phone"].values.tolist()).str.startswith(phone_number_start, na="False"))& (dataframe["State"]==state)]

如果你有:

help(search_phone_state)

它将打印:

Help on function search_phone_state in module __main__:


search_phone_state(phone_number_start, state, dataframe_path, separator)
returns records whose phone numbers begin with a phone_number_start and are from state

提交答案