与代码相矛盾的注释比没有注释还糟, 当代码更改时, 优先更新对应的注释!
注释应该是完整的句子. 如果一个注释是一个短语或句子, 它的第一个单词应该大写, 除非它是以小写字母开头的标识符(永远不要改变标识符的大小写!).
如果注释很短, 结尾的句号可以省略. 块注释一般由完整句子的一个或多个段落组成, 并且每句话结束有个句号.
在句尾结束的时候应该使用两个空格.
当用英文书写时, 遵循 Strunk and White (译注:Strunk and White, The Elements of Style)的书写风格.
在非英语国家的 Python 程序员, 请使用英文写注释, 除非你 120% 的确信你的代码不会被使用其他语言的人阅读.
块注释
块注释通常适用于跟随它们的某些 (或全部) 代码, 并缩进到与代码相同的级别. 块注释的每一行开头使用一个 #和一个空格(除非块注释内部缩进文本).
块注释内部的段落通过只有一个 #的空行分隔.,
行内注释
有节制地使用行内注释.
行内注释是与代码语句同行的注释. 行内注释和代码至少要有两个空格分隔. 注释由 #和一个空格开始.
事实上, 如果状态明显的话, 行内注释是不必要的, 反而会分散注意力. 比如说下面这样就不需要:
x = x + 1 # Increment x
但有时, 这样做很有用:
x = x + 1 # Compensate for border
文档字符串
要为所有的公共模块, 函数, 类以及方法编写文档说明. 非公共的方法没有必要, 但是应该有一个描述方法具体作用的注释. 这个注释应该在 def 那一行之后.
PEP 257 http://legacy.python.org/dev/peps/pep-0257/ 描述了写出好的文档说明相关的约定. 特别需要注意的是, 多行文档说明使用的结尾三引号应该自成一行, 例如:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
对于单行的文档说明, 尾部的三引号应该和文档在同一行.
来源: http://www.bubuko.com/infodetail-2696314.html