Python PEP8 编码规范 注释
Posted 40块钱抓娃娃
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Python PEP8 编码规范 注释相关的知识,希望对你有一定的参考价值。
与代码相矛盾的注释比没有注释还糟,当代码更改时,优先更新对应的注释!
注释应该是完整的句子。如果一个注释是一个短语或句子,它的第一个单词应该大写,除非它是以小写字母开头的标识符(永远不要改变标识符的大小写!)。
如果注释很短,结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成,并且每句话结束有个句号。
在句尾结束的时候应该使用两个空格。
当用英文书写时,遵循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 描述了写出好的文档说明相关的约定。特别需要注意的是,多行文档说明使用的结尾三引号应该自成一行,例如:
"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """
- 对于单行的文档说明,尾部的三引号应该和文档在同一行。
以上是关于Python PEP8 编码规范 注释的主要内容,如果未能解决你的问题,请参考以下文章