Python/源文件和注释
< 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
来获取该模块的文档。