文档字符串应该放在装饰器之前还是之后？

Question

比较以下。

示例 1：装饰器之前的文档字符串。

@app.route("/")
"""
summary
"""
def hello() -> str:
    return "Hello World"

对比示例 2：装饰器后的文档字符串：

"""
summary
"""
@app.route("/")
def hello() -> str:
    return "Hello World"

Answer 1

文档字符串应该放在哪里？

文档字符串应该放在函数内部，函数头之后的第一件事：

@app.route("/")
def hello() -> str:
    """
    summary
    """
    return "Hello World"

规范本身 (PEP 257) 使其明确：

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.

为什么？

这很重要，因为文档字符串不仅仅是一种约定。

如果将它们放在正确的位置，您可以使用 help() function（甚至其他工具）查看功能文档：

>>> @app.route("/")
... def hello() -> str:
...     """
...     summary
...     """
...     return "Hello World"
... 
>>> help(hello)
Help on function hello in module __main__:

hello() -> str
    summary

发生这种情况是因为，如果字符串文字是函数声明中的第一件事，解释器会将其设置为函数的 __doc__ 属性：

>>> hello.__doc__
'\n    summary\n    '

help() 基本上只是显示 __doc__ 属性的值，格式很好。

Answer 2

两者都不是，它们应该放在函数头下，如下所示：

@app.route("/")
def hello() -> str:
    """
    summary
    """
    return "Hello World"

PEP 257 更详细地讨论了文档字符串的约定。它指出这些文档字符串被设置为给定函数的 __doc__ 属性或 class（如上面链接的 PEP 中所述）。

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

调用help()时会出现这些文档字符串，如下所示：

>>> @app.route("/")
... def hello() -> str:
...     """
...     summary
...     """
...     return "Hello World"
...
>>> help(hello)
Help on function hello in module __main__:

hello() -> str
    summary

您描述的其他展示位置未设置 __doc__ 属性，因此与 help() 没有相同的行为。

文档字符串应该放在装饰器之前还是之后？

Should a docstring go before or after a decorator?

python

docstring

pep8

decorator

文档字符串应该放在哪里？

为什么？