Python开发编码规范

2020-03-11 15:52:09 浏览数 (1)

1.代码的缩进

4个空格一个缩进层次,永远不要混用制表符和空格. 最流行的Python缩进方式是仅使用空格, 其次是仅使用制表符.

代码语言:javascript复制
# 与左括号对齐
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',
    )

行的最大长度,将所有行限制在最大79字符.

代码语言:javascript复制
较长的代码行选择Python在小括号,中括号以及大括号中的隐式续行方式。
通过小括号内表达式的换行方式将长串折成多行。这种方式应该优先使用,而不是使用反斜杠续行。
反斜杠有时依然很有用。比如,比较长的,多个with状态语句,不能使用隐式续行,所以反斜杠是可以接受的:

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())

空行 顶层函数和类的定义,前后用两个空行隔开。 类里的方法定义用一个空行隔开。

编码

不论什么情况使用 UTF-8 吧!

2.导入

通常应该在单独的行中导入(Imports)

代码语言:javascript复制
推荐: import os
     import sys
不推荐:  import sys, os

导入总是位于文件的顶部,在模块注释和文档字符串之后,在模块的全局变量与常量之前。导入应该按照以下顺序分组:

代码语言:javascript复制
1.标准库导入
2.相关第三方库导入
3.本地应用/库特定导入
你应该在每一组导入之间加入空行。

3.空格

代码语言:javascript复制
紧跟在小括号,中括号或者大括号后。
Yes: spam(ham[1], {eggs: 2})
No:  spam( ham[ 1 ], { eggs: 2 } )

紧贴在逗号、分号或者冒号之前。
Yes: if x == 4: print x, y; x, y = y, x
No:  if x == 4 : print x , y ; x , y = y , x

然而,冒号在切片中就像二元运算符,在两边应该有相同数量的空格(把它当做优先级最低的操作符)。在扩展的切片操作中,所有的冒号必须有相同的间距。例外情况:当一个切片参数被省略时,空格就被省略了。
推荐:
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower offset : upper offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower   offset : upper   offset]

紧贴在函数参数的左括号之前。
Yes: spam(1)
No:  spam (1)

紧贴索引或者切片的左括号之前。
Yes: dct['key'] = lst[index]
No:  dct ['key'] = lst [index]

总是在二元运算符两边加一个空格:赋值(=),增量赋值( =,-=),
比较(==,<,>,!=,<>,<=,>=,in,not,in,is,is not),布尔(and, or, not)。
如果使用具有不同优先级的运算符,请考虑在具有最低优先级的运算符周围添加空格。
有时需要通过自己来判断;但是,不要使用一个以上的空格,并且在二元运算符的两边使用相同数量的空格。
i = i   1
submitted  = 1
x = x*2 - 1
hypot2 = x*x   y*y
c = (a b) * (a-b)

在制定关键字参数或者默认参数值的时候,不要在=附近加上空格。
推荐:
def complex(real, imag=0.0):
    return magic(r=real, i=imag)

不推荐:

def complex(real, imag = 0.0):
    return magic(r = real, i = imag)

4.注释

代码语言:javascript复制
注释块 (Block Comments)
注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次.
注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本).
注释块内的段落以仅含单个'#'的行分割.
注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段
的注释).

行内注释 (Inline Comments)
一个行内注释是和语句在同一行的注释.行内注释应该谨慎适用.
行内注释应该至少用两个空格和语句分开. 它们应该以'#'和单个空格开始.

5.文档化

编写好的文档说明(也叫“docstrings”)的约定在PEP 257中永恒不变。

要为所有的公共模块,函数,类以及方法编写文档说明。非公共的方法没有必要,但是应该有一个描述方法具体作用的注释。这个注释应该在def那一行之后。

PEP 257 描述了写出好的文档说明相关的约定。特别需要注意的是,多行文档说明使用的结尾三引号应该自成一行,例如:

代码语言:javascript复制
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

6.命名约定

应避免的名字

永远不要用字符`l'(小写字母el(就是读音,下同)), O'(大写字母oh),或I'(大写字母eye)作为单字符的变量名. 在某些字体中,这些字符不能与数字1和0分开.当想要使用'l'时,用'L'代替它.

模块名

模块应该是不含下划线的,简短的,小写的名字. 因为模块名被映射到文件名, 有些文件系统大小写不敏感并且截短长名字

类名 几乎没有例外,类名总是使用首字母大写单词串(CapWords)的约定.

异常名 趋势似乎是倾向使用CapWords异常名.

Constants 常量 常量通常定义在模块级,通过下划线分隔的全大写字母命名。例如:MAX_OVERFLOW 和 TOTAL。

全局变量名 这些约定与那些用于函数的约定差不多.被设计可以通过"from M import *"来使用的那些模块,应该在那些不想被导入的全局变量(还有内部函数和类)前加一个下划线).

函数名 函数名应该为小写,可能用下划线风格单词以增加可读性. mixedCase仅被允许用于这种风格已经占优势的上下文(如: threading.py) 以便保持向后兼容.

方法名和实例变量 与函数名类似

0 人点赞