PEP 257 - 文档字符串约定

前言

本文是对PEP 257 - 文档字符串约定的整理。

---

1 内容目录

---

2 重点摘抄

2.1. 什么是文档字符串？

1. 文档字符串是作为模块、函数、类或方法定义中的第一条语句出现的字符串文字。这样的文档字符串成为该__doc__对象的特殊属性。
2. 所有模块通常都应该有文档字符串，一个模块导出的所有函数和类也应该有文档字符串。公共方法（包括__init__构造函数）也应该有文档字符串。包可能记录在__init__.py包目录中文件的模块文档字符串中。
3. Python 代码中其他地方出现的字符串文字也可以作为文档。它们不被 Python 字节码编译器识别，也不能作为运行时对象属性访问（即未分配给__doc__）。

2.2. 文档字符串的两种形式

2.2.1. 单行

函数示例：

约定如下：

1. 即使字符串适合一行，也会使用三引号。这使得以后扩展它很容易。
2. 结束引号与开始引号在同一行。这对于单线来说看起来更好。
3. 文档字符串之前或之后都没有空行。
4. 文档字符串是以句点 . 结尾的短语。它将功能或方法的效果规定为命令（“执行此操作”、“返回该操作”），而不是描述；例如，不要写“返回路径名……”。
5. 单行文档字符串不应该是重复函数/方法参数的“签名”（可以通过自省获得）。

2.2.2. 多行

函数示例：

约定如下：

1. 多行文档字符串有一个像单行文档字符串一样的摘要行，然后是一个空行，然后是详情行。自动索引工具可以使用摘要行；重要的是它适合一行，并通过一个空行与文档字符串的其余部分分开。整个文档字符串的缩进与第一行的引号相同。
2. 类的文档字符串（单行或多行）之后插入一个空行——一般来说，类的方法之间用一个空行分隔。
3. 脚本（独立程序）的文档字符串应该可用作其“使用”消息，在使用不正确或缺少参数（或者可能使用“-h”选项，用于“帮助”）调用脚本时打印。这样的文档字符串应该记录脚本的函数和命令行语法、环境变量和文件。“使用”消息可以相当详细（几个屏幕已满）并且应该足以让新用户正确使用命令，以及成为老用户的完整快速参考。
4. 一个模块的文档字符串通常应该列出模块导出的类、异常和函数（以及任何其他对象），每个都有一行摘要。（这些摘要通常比对象文档字符串中的摘要行提供的详细信息少。）包的文档字符串（即包__init__.py模块的文档字符串）还应该列出包导出的模块和子包。
5. 函数或方法的文档字符串应总结其行为并记录其参数、返回值、引发的异常以及调用限制（如果适用）。应指明可选参数。应该记录关键字参数是否是接口的一部分。
6. 一个类的文档字符串应该总结它的行为并列出公共方法和实例变量。如果该类打算被子类化，并且具有子类的附加接口，则应单独列出该接口（在文档字符串中）。类构造函数应记录在其__init__ 方法的文档字符串中。各个方法应由其自己的文档字符串记录。
7. 如果一个类是另一个类的子类，并且它的行为主要是从那个类继承的，那么它的文档字符串应该提到这一点并总结差异。用动词“override”表示子类方法替换超类方法，不调用超类方法；使用动词“extend”表示子类方法调用超类方法（除了它自己的行为）。

2.3. 处理文档字符串缩进

1. 应该从文档字符串的开头和结尾删除空行。

示例1：

示例2：

---

3 其他

1. PEP 包含约定，而不是法律或语法。
2. 如果你违反了这些约定，你得到的最糟糕结果就是肮脏的外观。

---

4 推荐

1. 如果你是学了 C 语言之后再学习 Python，或者如果你想了解一下 Google 内部设定的 Docstring：Python的docstring规范（说明文档的规范写法）

---

总结

看完我就知道了，自己从来没有做到过。

---

---