Python 编程/源代码文档和注释

文档化是为代码留下信息的过程。Python 中执行此操作的两种机制是注释和文档字符串。

注释

总会有一个时间，你不得不返回到你的代码。也许是为了修复一个错误，或者添加一个新的功能。无论怎样，在六个月之后再去看你自己的代码，几乎和看别人的代码一样糟糕。你需要的是一种方法，用来提醒自己当初在做什么。

为此，你留下注释。注释是在代码中嵌入的小片段文本，Python 解释器会忽略它们。注释以井号 (#) 表示，并扩展到行尾。例如

#!/usr/bin/env python
# commentexample.py

# Display the knights that come after Scene 24
print("The Knights Who Say Ni!")
# print("I will never see the light of day!")

如你所见，你也可以使用注释来临时删除代码段，例如第二个 print 语句。

注释指南

以下指南来自 PEP 8，由 Guido van Rossum 编写。

通用
- 与代码相矛盾的注释比没有注释更糟糕。当代码发生变化时，始终优先考虑保持注释的最新状态！
- 注释应该使用完整的句子。如果注释是短语或句子，它的第一个单词应该大写，除非它是一个以小写字母开头的标识符（永远不要更改标识符的大小写！）。
- 如果注释很短，可以省略句末的句号。块注释通常由一个或多个由完整句子组成的段落组成，并且每个句子都应该以句号结尾。
- 句末句号后应该使用两个空格。
- 在用英语写作时，Strunk and White 的规则适用。
- 来自非英语国家的 Python 程序员：请用英语写注释，除非你 120% 确定代码永远不会被不讲你语言的人阅读。
行内注释
- 行内注释是指与语句在同一行的注释。行内注释应该与语句之间至少隔开两个空格。它们应该以 # 和一个空格开头。
- 如果行内注释陈述的是显而易见的事实，它们是多余的，事实上也会分散注意力。不要这样做
```
x = x + 1  # Increment x
```
  但有时，这样做是有用的
```
x = x + 1  # Compensate for border
```

文档字符串

但如果你只是想知道如何使用函数、类或方法怎么办？你可以在函数前面添加注释，但是注释是在代码内部的，所以你必须打开一个文本编辑器，并以这种方式查看它们。但是你无法从 C 扩展中提取注释，所以这不太理想。你始终可以编写一个单独的文本文件来描述如何调用函数，但这意味着你必须记住更新该文件。如果有一种机制可以让你嵌入文档并轻松访问它，那该多好啊……

幸运的是，Python 具有这样的功能。文档字符串（或 docstring）用于创建易于访问的文档。你可以通过将字符串作为第一个缩进语句添加到函数、类或模块中来添加 docstring。例如

#!/usr/bin/env python
# docstringexample.py

"""Example of using documentation strings."""

class Knight:
    """
    An example class.
    
    Call spam to get bacon.
    """
    
    def spam(eggs="bacon"):
        """Prints the argument given."""
        print(eggs)

惯例是使用三引号字符串，因为这使得添加跨越多行的文档变得更容易。

要访问文档，你可以在 Python shell 中使用 help 函数，并传入你想要查看其帮助信息的对应对象，或者你可以从系统 shell 中使用 pydoc 命令。如果我们在 docstringexample.py 所在的目录中，就可以输入 pydoc docstringexample 来获取有关该模块的文档。

前一节: 错误

索引

下一节: 习语