在非标准上下文中使用三引号创建“文档字符串”是一个好习惯吗？

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扩展将解析这些字符串以记录它们正上方的任何内容。在更改代码之前检查您是否正在使用类似的东西。