在 Python 文档字符串中，是否习惯于在参数列表中对齐 --？

Question

例如：

def foo(length, width):
    """Short desc.
    Arguments:
    length -- A desc.
    width  -- A desc.
    """

注意我是如何在"width"后面添加一个额外的空格的。

Answer 1

我认为这是一个选择的问题。

许多人实际上在他们的文档字符串中使用ReST，然后使用Sphinx生成文档。在这种情况下，可能会有一些要求，但我不认为划线对齐是其中之一。

我不喜欢对齐东西的想法，因为一旦你添加了需要重新对齐许多行的东西，就会让差异变得非常丑陋。

Answer 2

我不认为这有什么约定。所有关于函数的文档字符串的PEP 257都是

函数或方法的文档字符串应总结其行为，并记录其参数、返回值、副作用、引发的异常以及对何时可以调用它的限制（如果适用，请全部记录）。应指明可选参数。应该记录关键字参数是否是接口的一部分。

政治公众人物中给出的唯一例子也没有阐明这一点：

def complex(real=0.0, imag=0.0):
    """Form a complex number.
    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

我通常会把破折号对齐，但我不认为有一个通用的约定。

Answer 3

我喜欢您的示例（对齐--），并认为它使文档字符串更易于阅读。

这方面没有PEP 8风格的标准，所以你最终做什么在很大程度上是一个品味问题。话虽如此，在标准库中也有一些先例。例如，以下内容取自poplib模块的文档字符串：

class POP3:
    """This class supports both the minimal and optional command sets.
    Arguments can be strings or integers (where appropriate)
    (e.g.: retr(1) and retr('1') both work equally well.
    Minimal Command Set:
            USER name               user(name)
            PASS string             pass_(string)
            STAT                    stat()
            LIST [msg]              list(msg = None)
            RETR msg                retr(msg)
            DELE msg                dele(msg)
            NOOP                    noop()
            RSET                    rset()
            QUIT                    quit()
    """