前文传送门:
Python代码这样写才规范优雅! (一)
Python代码这样写才规范优雅! (二)
参考:
https://www.python.org/dev/peps/pep-0008/
Python PEP8编码规范的内容如下:
1. Introduction 介绍2. A Foolish Consistency is the Hobgoblin of Little Minds 尽信书,则不如无书3. Code lay-out 代码布局3.1 Indentation 缩进3.2 Tabs or Spaces? 制表符还是空格?3.3 Maximum Line Length 行的最大长度3.4 Should a line break before or after a binary operator? 在二元运算符之前应该换行吗?3.5 Blank Lines 空行3.6 Source File Encoding 源文件编码3.7 Imports 导入3.8 Module level dunder names 模块级的“呆”名4. String Quotes 字符串引号5. Whitespace in Expressions and Statements 表达式和语句中的空格5.1 Pet Peeves 不能忍受的事情5.2 Other Recommendations 其他建议6. Comments 注释6.1 Block Comments 块注释6.2 Inline Comments 行内注释6.3 Documentation Strings 文档字符串7. Naming Conventions 命名规范7.1 Overriding Principle 最重要的原则7.2 Descriptive: Naming Styles 描述:命名风格7.3 Prescriptive: Naming Conventions 约定俗成:命名约定7.4 Public and internal interfaces 公共和内部的接口8. Programming Recommendations 编程建议8.1 Function Annotations 功能注释9. 参考
我们接着上一篇的内容继续看:
6. Comments 注释
与代码相矛盾的注释比没有注释还糟,当代码更改时,优先更新对应的注释!
注释应该是完整的句子。如果一个注释是一个短语或句子,它的第一个单词应该大写,除非它是以小写字母开头的标识符(永远不要改变标识符的大小写!)。
如果注释很短,结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成,并且每句话结束有个句号。
在句尾结束的时候应该使用两个空格。
当用英文书写时,遵循Strunk and White (译注:《Strunk and White, The Elements of Style》)的书写风格。
在非英语国家的Python程序员,请使用英文写注释,除非你120%的确信你的代码不会被使用其他语言的人阅读。
6.1 Block Comments 块注释
块注释通常适用于跟随它们的某些(或全部)代码,并缩进到与代码相同的级别。块注释的每一行开头使用一个#和一个空格(除非块注释内部缩进文本)。
块注释内部的段落通过只有一个#的空行分隔。
6.2 Inline Comments 行内注释
有节制地使用行内注释。
行内注释是与代码语句同行的注释。行内注释和代码至少要有两个空格分隔。注释由#和一个空格开始。
事实上,如果状态明显的话,行内注释是不必要的,反而会分散注意力。比如说下面这样就不需要:
x = x + 1 # Increment x
但有时,这样做很有用:
x = x + 1 # Compensate for border
6.3 Documentation Strings 文档字符串
编写好的文档说明(也叫“docstrings”)的约定在PEP257中永恒不变。
要为所有的公共模块,函数,类以及方法编写文档说明。非公共的方法没有必要,但是应该有一个描述方法具体作用的注释。这个注释应该在def那一行之后。
PEP257 描述了写出好的文档说明相关的约定。特别需要注意的是,多行文档说明使用的结尾三引号应该自成一行,例如:
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first.
"""
对于单行的文档说明,尾部的三引号应该和文档在同一行。
7. Naming Conventions 命名规范
Python库的命名规范很乱,从来没能做到完全一致。但是目前有一些推荐的命名标准。新的模块和包(包括第三方框架)应该用这套标准,但当一个已有库采用了不同的风格,推荐保持内部一致性。
7.1 Overriding Principle 最重要的原则
那些暴露给用户的API接口的命名,应该遵循反映使用场景而不是实现的原则。
7.2 Descriptive: Naming Styles 描述:命名风格
有许多不同的命名风格。这里能够帮助大家识别正在使用什么样的命名风格,而不考虑他们为什么使用。
以下是常见的命名方式:
- b(单个小写字母)
- B(单个大写字母)
- lowercase 小写字母
- lower_case_with_underscores 使用下划线分隔的小写字母
- UPPERCASE 大写字母
- UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母
- CapitalizedWords(或者叫 CapWords,或者叫CamelCase 驼峰命名法 —— 这么命名是因为字母看上去有起伏的外观)。有时候也被称为StudlyCaps。
- 注意:当在首字母大写的风格中用到缩写时,所有缩写的字母用大写,因此,HTTPServerError 比 HttpServerError 好。
- mixedCase(不同于首字母大写,第一个单词的首字母小写)
- Capitalized_Words_With_Underscores(巨丑无比!)
- _single_leading_underscore:(单下划线开头)弱“内部使用”指示器。比如 from M import * 是不会导入以下划线开始的对象的。
- single_trailing_underscore_:(单下划线结尾)这是避免和Python内部关键词冲突的一种约定,比如:Tkinter.Toplevel(master, class_=’ClassName’)
- __double_leading_underscore:(双下划线开头)当这样命名一个类的属性时,调用它的时候名字会做矫正(在类FooBar中,__boo变成了_FooBar__boo;见下文)。
- __double_leading_and_trailing_underscore__:(双下划线开头,双下划线结尾)“magic”对象或者存在于用户控制的命名空间内的属性,例如:__init__,__import__或者__file__。除了作为文档之外,永远不要命这样的名。
- 公共属性不应该有前缀下划线。
- 如果公共属性名和关键字冲突,在属性名之后增加一个下划线。这比缩写和随意拼写好很多。(然而,尽管有这样的规则,在作为参数或者变量时,‘cls’是表示‘类’最好的选择,特别是作为类方法的第一个参数。)注意1:参考之前的类方法参数命名建议
- 对于单一的共有属性数据,最好直接对外暴露它的变量名,而不是通过负责的 存取器(accessor)/突变(mutator) 方法。请记住,如果你发现一个简单的属性需要成长为一个功能行为,那么Python为这种将来会出现的扩展提供了一个简单的途径。在这种情况下,使用属性去隐藏属性数据访问背后的逻辑。注意1:属性只在new-style类中起作用。 注意2:尽管功能方法对于类似缓存的负面影响比较小,但还是要尽量避免。 注意3:属性标记会让调用者认为开销(相当的)小,避免用属性做开销大的计算。
- 如果你的类打算用来继承的话,并且这个类里有不希望子类使用的属性,就要考虑使用双下划线前缀并且没有后缀下划线的命名方式。这会调用Python的命名转换算法,将类的名字加入到属性名里。这样做可以帮助避免在子类中不小心包含了相同的属性名而产生的冲突。注意1:只有类名才会整合进属性名,如果子类的属性名和类名和父类都相同,那么你还是会有命名冲突的问题。 注意2:命名转换会在某些场景使用起来不太方便,例如调试,__getattr__()。然而命名转换的算法有很好的文档说明并且很好操作。 注意3:不是所有人都喜欢命名转换。尽量避免意外的名字冲突和潜在的高级调用。