Python编程

文档编写是留下有关代码信息的过程。在 Python 中，文档编写的两种机制是注释和文档字符串。

注释

无论何时，你总会需要回到你的代码中。也许是为了修复一个 bug，或者添加一个新功能。不管怎样，六个月后再看自己的代码，几乎跟看别人的代码一样糟糕。你需要的是一种方法，来提醒自己当时在做什么。

为此，你可以使用注释。注释是嵌入到代码中的小段文本，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 和 White 的规范。
• 非英语国家的 Python 编程人员：请使用英语编写注释，除非你百分之百确定代码永远不会被不会说你语言的人阅读。

内联注释

内联注释是与语句位于同一行的注释。内联注释应至少与语句之间有两个空格的间隔。注释应以 # 和一个空格开始。

• 如果注释说明显而易见，它就不必要，实际上可能会分散注意力。不要这样做：

  x = x + 1  # Increment x
  

• 但有时，这样做是有用的：

  x = x + 1  # Compensate for border
  

文档字符串

但是如果你只是想知道如何使用一个函数、类或方法呢？你可以在函数前添加注释，但注释是内嵌在代码中的，这意味着你需要打开文本编辑器来查看它们。但你无法从 C 扩展中查看注释，所以这并不是理想的做法。你当然可以写一个单独的文本文件，描述如何调用函数，但那样你就需要记得更新这个文件。如果有一种机制可以方便地将文档嵌入并轻松访问就好了……

幸运的是，Python 具备这样的能力。文档字符串（或 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 来获取该模块的文档。