PEP8 中文翻译，python的编程规范

英文原文地址：

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.方法名和实例变量：小写+下划线

 

结束