Python编程规范(PEP8)
代码布局
缩进
对于每一次缩进使用4个空格。使用括号、中括号、大括号进行垂直对齐,或者缩进对齐。
制表符还是空格?
永远不要将制表符与空格混合使用。Python最常用的缩进方式是只是用空格。
当调用Python命令行的 -t 选项时,它会检测并警告代码非法混合使用制表符和空格。当使用 -tt 选项时,警告变成了错误。
最大行长度
限制所有行最长为79个字符。
使用反斜杠来分行是一个很好的选择。
我们应当选择在二元操作符之后进行分行,而不是之前。
空行
使用两行空行来分隔顶层函数和类定义。
使用单行空行来分隔类方法定义。
在函数中使用空行来表示不同的逻辑块。
编码
Python核心发行代码里面优先使用ASCII码或Latin-1编码。3.0后UTF-8编码优先于Latin-1。
导入
每一个导入通常应当使用单独的行。
导入应当位于文件顶部,在模块注释和文档字符串之后,在全局变量和常量之前。
导入应当按以下顺序分组,且每组导入之间使用空行隔开:
1、标准库导入
2、第三方库导入
3、本地应用程序/定制库导入
使用绝对包路径导入。
表达式和语句中的空格
注释
误导的注释不如没有注释
注释应当为完整的句子,且句号结尾的句子后面应当有2个空格。如果注释很短,那么结尾的句号可以忽略。
块注释
块注释应当和代码缩进保持一致。每行注释开头应以#开头,然后紧跟一个空格。
行注释
行注释至少和语句间隔2个空格。同样的注释应当以#开头,然后紧跟一个空格。
文档字符串
对于所有的公有模块、类、函数和方法都需要编写文档字符串。
""" 作为多行的文档字符串的结束,应该单独一行,并且之前有一个空行。
对于只有一行的文档字符串来说,结尾的 """ 在同一行。
更详细的文档字符串规范见 PEP 257。
命名规范
目前Python库的命名规范尚未达成一致,但有一些推荐的标准。
在Python里面,有一些具有特定意义的下划线前缀或者后继的特殊格式。如:
1、_single_leading_underscore:(单下划线开始)弱"内部使用"指示器。例如:from M import * 不会导入以下划线开始的对象。
2、single_trailing_underscore_:(单下划线结束)规定使用其来避免与Python关键字冲突,例如:
Tkinter.Toplevel(master, class_='ClassName') 在参数class后面加单下划线,避免与关键字class冲突
3、__double_leading_underscore:(双下划线开始)命名一个类的属性时,调用"name mangling"(类FooBar中,__boo 变为了 _FooBar__boo; 见下文)
4、__double_leading_and_trailing_underscore__:(双下划线开始和结束)存活在用户控制命名空间的"magic"对象或属性。 例如__init__, __import__ 或 __file__。永远不要起这样的名字。
避免使用的命名
不要使用小写的L、大写的O、以及大写的I作为单字符变量名。
包与模块名称
模块应当使用简短、全小写的名字,也可使用下划线连接来提高可读性。
包也应当使用简短、全小写的名字,但不要使用下划线。
这是由于模块名与文件名关联,而在某些文件系统中大小写不敏感,且会截断过长的名字。
当使用C/C++来编写一个扩展模块时,应当使用下划线作为模块名的前缀。
类名
类名应当使用驼峰式(CapWords)。内部使用的类名应当加下划线前缀。
异常名
异常也是一个类,所以需要遵循类名规则。但如果你的异常确实是个错误的话,请使用Error前缀。
全局变量名
遵循函数规则。
函数名
函数名全小写,可以使用下划线分隔来提高可读性。
函数与方法参数
使用self作为实例方法的第一个参数。
使用cls作为类方法的第一个参数。
当函数的参数名与保留字冲突时,使用下划线后缀(第二次提醒)。
方法名与实例变量
遵循函数规则。
在私有方法和实例变量前用单下划线前缀。
使用双下划线前缀来调用"name mangling"来避免与子类命名冲突。
如果类Foo有个属性叫__a,那么它不能使用Foo.__a读取,但仍然可以Foo._Foo__a来读取。
常量
常量通常在模块级别定义,使用全大写和下划线分隔的形式。
继承设计
在设计类的方法或实例变量时,应当觉得其实公有的还是非公有的。当不能确定时,设计为私有的。
在Python中没有真正的私有属性。
公有属性不应当使用下划线开始。
当公有属性与保留字冲突时,在名称后面加下划线后缀(第三次提醒)。
对于简单的公有属性,最好直接访问其属性名,而非get/set方法。
编程建议
代码应当适用于Python的多个实现。比如不要依赖CPython的高效字符串语句 a+=b,而应当使用join,从而保证在不同实现上的线性开销。
当与类似于None的单例(singleton)进行比较式,要使用is 或者 is not, 而不是使用等于操作。
当使用复杂比较实现排序操作时,最好实现全部的六个比较操作。
使用基于对象的异常。
模块或者包应当定义自己的异常基类,这个类应当继承自内置的Exception类。
当抛出一个异常的时候,使用raise ValueError('message')代替旧的raise ValueError, 'message'格式。这是由于当异常的参数很长或者是格式化字符串的时候,由于括号的关系,我们不需要使用多行连接符。 旧的格式在Python 3 中被移除。
当捕获一个异常的时候,要用详细的异常声明来代替简单的except: 语句。
一个空的except:语句将会捕获 SystemExit 和 KeyboardInterrrupt 异常。这会使得很难用Control-C来中断一个程序,并且还会隐藏其他的问题。
另外,对于所有的try/except语句,限制try语句来减少必要代码的数量。 再者,可以避免掩盖问题。
Yes:
try: value = collection[key] except KeyError: return key_not_found(key) else: return handle_value(value)
No:
try: # Too broad! return handle_value(collection[key]) except KeyError: # Will also catch KeyError raised by handle_value() return key_not_found(key)
使用''.startswith() 和 ''.endswith()而非字符切片去检测前缀或后缀。
对象类型比较总要用 isinstance() 而非直接比较。
对于序列,(strings, lists, tuples),利用空序列为false这一点来进行判断,而非使用长度来判断。
别用‘==’进行布尔值和 True 或者 False 的比较。