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!")

如您所见，您还可以使用注释暂时删除代码段，例如第二条打印语句。

注释指南

以下准则来自 PEP 8，由 Guido van Rossum 编写。

常规
- 与代码相矛盾的注释比没有注释更糟糕。始终优先考虑在代码更改时保持注释的更新！
- 注释应为完整的句子。如果注释是短语或句子，则其第一个单词应大写，除非它是以小写字母开头的标识符（切勿改变标识符的大小写！）。
- 如果注释很短，则可以省略末尾的句号。块注释通常由一个或多个由完整句子构成的段落组成，每个句子都应以句号结尾。
- 句末句号后应使用两个空格。
- 撰写英语时，适用 Strunk and White。
- 来自非英语国家的 Python 程序员：请用英语撰写注释，除非您 120% 确定代码不会被不讲您语言的人阅读。
内联注释
- 内联注释是与语句在同一行的注释。内联注释应与语句至少相隔两个空格。它们应以 # 和一个空格开头。
- 内联注释没有必要，如果陈述显而易见的内容，实际上会分散注意力。不要这样做：
```
x = x + 1 # 增加 x
```
  但有时，这很有用：
```
x = x + 1 # 补偿边框
```

文档字符串

但是，如果您只是想知道如何使用函数、类或方法，该怎么办？您可以在函数前添加注释，但注释在代码内部，因此您必须打开文本编辑器并以这种方式查看它们。但是您无法从 C 扩展中调出注释，因此这并不理想。您可以随时编写一个单独的文本文件来说明如何调用函数，但这意味着您必须记住更新该文件。如果只有一种机制能够嵌入文档并轻松获取它...

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

#!/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 来获取该模块的文档。