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

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）明确表示：

文档字符串是一个字符串文字，作为模块、函数、类或方法定义中的第一个语句出现。

为什么？

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

如果将它们放在正确的位置，您可以看到该函数的函数文档help()（甚至可能是其他工具）：

>>> @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__给定函数或类的属性（如上面链接的 PEP 中所述）。

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

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

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

hello() -> str
    summary

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