在Python文档字符串中，参数列表中的--是否需要对齐？

Question

举个例子：

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

    Arguments:

    length -- A desc.
    width  -- A desc.
    """

注意我在“width”后面加了一个额外的空格。

Answer 1

我很喜欢你的例子（对齐 --），我觉得这样可以让文档字符串一眼看上去更容易读懂。

其实对于这个没有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()

    """

Answer 2

我觉得这主要是个人选择的问题。

很多人其实在他们的文档字符串里使用ReST，然后用Sphinx来生成文档。在这种情况下可能会有一些要求，但我觉得对齐破折号并不是其中之一。

我不太喜欢对齐的想法，因为一旦你添加了需要重新对齐很多行的内容，差异就会变得非常难看。

Answer 3

我觉得这方面没有什么固定的规则。所有PEP 257对函数的文档字符串（docstring）说的就是：

一个函数或方法的文档字符串应该总结它的行为，并记录它的参数、返回值、可能的副作用、抛出的异常，以及调用时的限制（如果适用的话）。可选参数也应该标明。还要说明关键字参数是否是接口的一部分。

PEP中给出的唯一例子也没有对此做出明确的说明：

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
    ...

我通常会对齐破折号，但我觉得没有一个普遍的规则。

在Python文档字符串中，参数列表中的--是否需要对齐？

3 个回答

撰写回答