13

PEP 257 说：

在记录一个类的所有文档字符串（单行或多行）之前和之后插入一个空行——一般来说，类的方法之间用一个空行分隔，文档字符串需要从第一种方法是空行；为了对称，在类头和文档字符串之间放一个空行。

但我似乎找不到任何实际实现这一点的代码。

我检查了 Python 2.6 提供的几个标准模块，甚至专门搜索了提到 Guido 名字的模块。但即使是 rietveld 代码审查工具的代码，恕我直言也不符合（参见例如http://code.google.com/p/rietveld/source/browse/upload.py）：

class CondensedHelpFormatter(optparse.IndentedHelpFormatter):
   """Frees more horizontal space by removing indentation from group
      options and collapsing arguments between short and long, e.g.
      '-o ARG, --opt=ARG' to -o --opt ARG"""

   def format_heading(self, heading):
     return "%s:\n" % heading

这个多行文档字符串之前没有空行，之后的空行在右引号之外。

此类 from/usr/lib64/python2.6/site.py之前没有空行，但在右引号之前和之后有一个空行。

class _Helper(object):
    """Define the built-in 'help'.
    This is a wrapper around pydoc.help (with a twist).

    """

    def __repr__(self):

是否有可用于演示 PEP 257 的示例？

提前致谢

4

3 回答 3

10

不是直接的答案，但如果你想遵守 PEP257，你可以使用我写的工具： https ://github.com/halst/pep257

我也很震惊地看到有多少代码（也在标准库中）甚至没有尝试遵守 PEP257。

可能大部分人都觉得他们的docstring风格有道理，我也觉得PEP257风格有点别扭，但是用了一段时间就爱上了，觉得这是最漂亮的方式编写文档字符串。我总是在我能做的每一个方面都遵循 PEP257，并编写了这个工具，以便更多的人可以看到他们如何改进自己的风格。

举个例子，我对 PEP8 和pep8 工具有一个有趣的体验：当我第一次阅读 PEP8 时，我喜欢它并认为我遵循它，但是当我在 pep8 上尝试我的代码时，我对我离 PEP8 有多远，以及如何在我修复了这些样式错误之后，我的代码看起来会更好。

我希望人们对 pep257 也有类似的体验，并从此开始愉快地关注 PEP257。

于 2012-04-08T19:35:14.773 回答
0

据我所知，您链接到的文件说：

在记录一个类的所有文档字符串（单行或多行）之后插入一个空行——一般来说，类的方法之间用一个空行分隔，并且文档字符串需要从第一个方法偏移由一个空行。

（强调我的）

因此，您提供的示例都是正确的，因为它们在文档字符串之后有一个空行，因此将下一个方法声明与一个空行分开。

于 2015-03-04T12:23:59.713 回答
-1

这是一些 pep(Python Enhancement Proposal) python 示例示例首先我们选择要使用的版本，因为这个示例与 pep-8 最相似。所以我们必须提供函数描述、参数和返回类型...... 

def foo(bar, spam, eggs):
        """
        Some function

        :param bar: parameter that requires description
        :param spam: parameter that requires description
        :param eggs:
        :return xyz: parameter description
        """

根据 google style 包含 python 样式的优秀指南。这提供了比 PEP-257 更好的指导，这里是参考链接：google style guide

def sample_fun(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass
于 2020-06-16T11:51:30.517 回答