30

编写 Python 文档字符串的首选方法是什么？

"""或者"

在 Dive Into Python一书中，作者提供了以下示例：

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

    Returns string."""

在另一章中，作者提供了另一个例子：

def stripnulls(data):
    "strip whitespace and nulls"
    return data.replace("\00", "").strip()

两种语法都有效。对我来说唯一的区别是它"""允许我们编写多行文档。

除此之外还有什么不同吗？

4

3 回答 3

42

来自PEP8 风格指南：

  • PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该单独一行，例如：

    """Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

  • 对于一个班轮文档字符串，可以将结束的 """ 保持在同一行。

PEP 257建议使用三引号，即使是单行文档字符串：

  • 即使字符串适合一行，也会使用三引号。这使得以后扩展它很容易。

请注意，即使 Python 标准库本身也不会始终如一地遵循这些建议。例如，

于 2013-07-14T21:24:44.973 回答
10

它们都是字符串，所以没有区别。首选样式是三重双引号（PEP 257）：

为了保持一致性，请始终"""triple double quotes"""围绕文档字符串使用。

如果r"""raw triple double quotes"""您在文档字符串中使用任何反斜杠，请使用。对于 Unicode 文档字符串，使用u"""Unicode triple-quoted strings""".

于 2013-07-14T21:24:06.400 回答
0

不，不是。如果您正在写入文件，使用三引号可能是理想的，因为您不必使用“\n”来下一行。只需确保您开始和结束的引号是相同的类型（双引号或三引号）。如果您还有其他问题，这里是一个可靠的资源：

http://docs.python.org/release/1.5.1p1/tut/strings.html

于 2013-07-14T21:29:33.437 回答