英文原文地址:
http://legacy.python.org/dev/peps/pep-0008/
原文太长,这里展示一部分规范。
介绍
本文档改编自《Guido's original Python Style Guide essay》,还有一些来自《Barry's style guide》
一致性并不一定对(A Foolish Consistency is the Hobgoblin of Little Minds)
代码更多的是为了让人去读。
一致性很重要。但是更重要的是:知道何时保持一致性,很多时候不应该用代码规范。
下面的情况忽略掉代码规范:
- 当用上代码规范后,让代码不容易阅读。
- 和周围代码保持一直(可能是历史代码)
- 由于代码的原因,没有任何理由修改代码(除了使用代码规范)
- 与旧版本保持一直,或不支持代码规范中的写法
代码布局
Indentation(缩进)
使用4个空格
下面是带括号的一些缩进情况。
Yes:
# 和括号开始的部分对齐
foo = long_function_name(var_one, var_two,
var_three, var_four)
#需要更多一层的缩进
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
No:
# 禁止对齐下一层的代码
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 需要进一层的缩进,区分下一层的代码
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
还可以用下面的风格:
# 不需要额外的缩进
foo = long_function_name(
var_one, var_two,
var_three, var_four)
在闭合的括号中,可以选择下面两种方式,都行:
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
空格或者Tab
空格是绝对的首选。
python3 已经不允许空格和Tab混用了。
每行最大字符数
修改每行最大字符数到79,因为python标准库就是每行最大79个字符,
如果太长使用 反斜杠来换行:
with open('/path/to/some/file/you/want/to/read') as file_1, \
open('/path/to/some/file/being/written', 'w') as file_2:
file_2.write(file_1.read())
下面是在括号中换行的情况:
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if (width == 0 and height == 0 and
color == 'red' and emphasis == 'strong' or
highlight > 100):
raise ValueError("sorry, you lose")
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
raise ValueError("I don't think so -- values are %s, %s" %
(width, height))
Blob.__init__(self, width, height,
color, emphasis, highlight)
源码文件的编码
python2 默认ASCII ,python3 默认utf8
用utf8省事
import的使用
分行包含:
Yes: import os
import sys
No: import sys, os
下面的也可以:
from subprocess import Popen, PIPE
包含顺序也有讲究,顺序如下(他们之间最好加一个换行):
- 标准库
- 第三方库
- 本地的应用或者库
使用绝对路径import,不用import * ,可能会导入到名字相同的冲突的包
表达式和语句中的空格
避免多余的空格
1.括号里:
Yes: spam(ham[1], {eggs: 2})
No: spam( ham[ 1 ], { eggs: 2 } )
2.逗号,冒号,分号 之后:
Yes: if x == 4: print x, y; x, y = y, x
No: if x == 4 : print x , y ; x , y = y , x
3.方法调用:
Yes: spam(1)
No: spam (1)
4.数组索引
Yes: dict['key'] = list[index]
No: dict ['key'] = list [index]
5.多个赋值(或其他)操作:
Yes:
x = 1
y = 2
long_variable = 3
No:
x = 1
y = 2
long_variable = 3
其它建议
1.对于 assignment (=),augmented assignment (+=, -= etc.), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).,需要加上空格
Yes:
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)
No:
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
2.当=用于给参数赋默认值的时候,不要加空格
Yes:
def complex(real, imag=0.0):
return magic(r=real, i=imag)
No:
def complex(real, imag = 0.0):
return magic(r = real, i = imag)
3.多操作的时候,要换行
Yes:
if foo == 'blah':
do_blah_thing()
do_one()
do_two()
do_three()
Rather not:
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()
注释
优先更新注释,用英语写
命名
1.模块名短一点,都小写,用下划线。因为模块会映射到文件的名字,所以避免和系统限制冲突(大小写不区分,长度限制等)
2.类名:首字母大写,内部类加入前导下划线
3.异常名:加入后缀Error
4.函数名:小写+下划线
5.函数和方法的参数:实例使用self 开始,类使用cls 开始。如果和系统参数名重复,在其后加_
6.方法名和实例变量:小写+下划线