本节中的函数是指函数、方法、生成器 (generator) 和特性 (property).

满足下列任意特征的任何函数都必须有文档字符串:

公开 API 的一部分

长度过长

逻辑不能一目了然

文档字符串应该提供充分的信息, 让调用者无需阅读函数的代码就能调用函数. 文档字符串应该描述函数的调用语法和语义信息, 而不应该描述具体的实现细节, 除非这些细节会影响函数的用法. 比如, 如果函数的副作用是会修改某个传入的对象, 那就需要在文档字符串中说明. 对于微妙、重要但是与调用者无关的实现细节, 相较于在文档字符串里说明, 还是在代码中间加注释更好.

文档字符串可以是陈述句 ("""Fetches rows from a Bigtable.""") 或者祈使句 ("""Fetch rows from a Bigtable."""), 不过一个文件内的风格应当一致. 对于 @property 修饰的数据描述符 (data descriptor), 文档字符串应采用和属性 (attribute) 或 函数参数 一样的风格 ("""Bigtable 路径.""" 而非 """返回 Bigtable 路径.""").

对于覆写 (override) 基类 (base class) 方法的子类方法, 可以用简单的文档字符串引导读者阅读基类方法的文档字符串, 比如 """参见基类."""". 这样是为了避免到处复制基类方法中已有的文档字符串. 然而, 如果覆写的子类方法与基类方法截然不同, 或者有更多细节需要记录 (例如有额外的的副作用), 那么子类方法的文档字符串中至少要描述这些区别.

函数的部分特征应该在以下列出特殊小节中记录. 每小节有一行标题, 标题以冒号结尾. 除标题行外, 小节的其他部分应有2个或4个空格 (同一文件内应保持一致) 的悬挂缩进. 如果函数名和函数签名 (signature) 可以见名知意, 以至于一行文档字符串就能恰当地描述该函数, 那么可以省略这些小节.