python - 在非标准上下文中使用三引号创建 "docstrings"是一种好习惯吗？

Question

我正在查看某人的代码，其中到处都是这种“文档字符串”:

SLEEP_TIME_ON_FAILURE = 5
"""Time to keep the connection open in case of failure."""

SOCKET_TIMEOUT = 15
"""Socket timeout for inherited socket."""

...

根据 Python 文档，文档字符串仅适用于模块、类或方法开头的上下文。

上述非标准做法的含义是什么？为什么 Python 允许这样做？这不会影响性能吗？

Answer 1

就 Python 而言，这些不是文档字符串。它们只是用作表达式语句的字符串文字。你可以这样做——你可以使用任何有效的 Python 表达式作为它自己的语句。 Python 不关心表达式是否实际执行任何操作。对于单独一行的字符串，唯一的性能影响是字节码编译时的少量额外工作；在运行时没有影响，因为这些字符串已被优化。

一些文档生成器会查看这些字符串。比如很常见的Sphinx autodoc扩展将解析这些字符串以记录它们正上方的任何内容。在更改代码之前检查您是否正在使用类似的东西。