Question

在C＃和Visual Studio中，可以对你的函数进行注释，这样你就可以告诉谁在使用你的类输入参数应该是什么，它应该返回什么，等等。在python中有什么远程类似的东西？

Answer 1

在Python中，您使用docstrings，如下所示：

def foo():
    """ Here is the docstring """

基本上，您需要在函数，类或模块的第一行上使用三引号字符串才能将其视为文档字符串。

注意：实际上我没有使用三重引号字符串，但这是惯例。任何升的字符串都可以，但最好坚持使用约定并使用三重引号字符串。

Answer 2

我认为你所得到的是C＃对于代码注释的格式化具有强烈的文化习惯，而Visual Studio提供了一起收集这些注释的工具，根据商定的标记格式化它们，等等。 Java与Javadoc类似。

Python有一些像这样的约定，但它们并不那么强大。 PEP 257涵盖了最佳实践，像Sphinx这样的工具可以很好地将它们收集在一起以生成文档。

正如其他答案所解释的那样，docstrings是模块，类或函数中的第一个字符串。从词汇上讲，它们只是一个字符串（通常是三引号以允许多行文档），但它们保留为实体的__doc__属性，因此可以通过工具轻松进行内省。

Answer 3

正如其他答案中所提到的，函数最顶部的字符串用作文档，如下所示：

>>> def fact(n):
...     """Calculate the factorial of a number.
... 
...     Return the factorial for any non-negative integer.
...     It is the responsibility of the caller not to pass
...     non-integers or negative numbers.
... 
...     """
...     if n == 0:
...         return 1
...     else:
...         return fact(n-1) * n
...

要在Python解释器中查看函数的文档，请使用help：

>>> help(fact)
Help on function fact in module __main__:

fact(n)
    Calculate the factorial of a number.

    Return the factorial for any non-negative integer.
    It is the responsibility of the caller not to pass
    non-integers or negative numbers.
(END)

许多从代码生成HTML文档的工具使用第一行作为函数的摘要，而字符串的其余部分提供了其他详细信息。因此，第一行应该保持简短，以便很好地适应生成文档中的函数列表。

Answer 4

只需将字符串放在任何你喜欢的地方。如果有一个字符串作为方法中的第一件事，Python会把它放在特殊字段__doc__中：

def f():
    """This is the documentation"""
    pass
    """But you can have as many comments as you like."""
print f.__doc__

Python代码注释

4 个答案: