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

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__ 属性的值。