python - 可以使用 python 文档字符串来编写代码吗？

Question

我开发了一个 python 脚本，它将在服务器构建上运行验收测试。

我使用了一种方案，其中通用测试函数将在文档字符串中包含测试名称和测试先决条件。执行函数将解析测试函数上的文档字符串，并使用文档字符串中的名称进行标记，并使用后续行来验证测试依赖项是否得到满足(如果依赖项失败，则运行测试没有意义)。

func _test_1(self):
     """
     Name: Test foo
     Test bar
     """

我完成了这项工作，但我想知道这在 python 社区中是否普遍可以接受。 除了文档或代码描述之外，使用文档字符串还有什么注意事项吗？

Answer 1

当然是；甚至有一个标准库工具可以执行此操作: doctest :

The doctest module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest:

• To check that a module’s docstrings are up-to-date by verifying that all interactive examples still work as documented.
• To perform regression testing by verifying that interactive examples from a test file or a test object work as expected.
• To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of “literate testing” or “executable documentation”.

显然，您想到了一个其他人认为适用范围足够广泛的想法，足以使其成为 Python 库的核心功能。

文档字符串只是文本，您可以为该文本添加您想要赋予的任何含义。这里没有任何警告!