Python----Python编码规范-阿里云开发者社区

【原文链接】

一、布局

1.1 缩进

每一级缩进使用4个空格
类似定义函数或者调用函数时参数过多的场景，有两种推荐缩进做法，一种是第一行有参数，换行后利用

括号默认的垂直对齐方式。另一种方式就是第一行没有参数，参数直接换行到下一行，此时
缩进需要比其他代码多缩进一级，便于轻松识别出不是其他的代码语句

if语句中条件比较多需要换行时，推荐两种处理方式，一种是判断条件和代码之间

增加一行注释，另外一种就是对条件做更多一层的缩进，从而用于语句块中的代码区分开

当多行结构中使用的括号（小括号、方括号、花括号）的右括号另起一行的时候，可以与上一行的第一个字符对齐

或者也可以与下一行的第一个字符对齐

# 以下代码为推荐代码：
def long_function_name(var_one,
                   var_two, 
                   var_three,
                   var_four):
    print(var_one)
  
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)
  
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

if (this_is_one_thing and
    that_is_another_thing):
    # 当满足某种条件时执行此分支.
    do_something()
  
if (this_is_one_thing
        and that_is_another_thing):
    do_something()
  
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',
)

# 以下代码为不推荐代码
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)
  
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

1.2 Tabs 键还是空格键

空格是首选的缩进方式
如果使用tab键则所有缩进均需要使用tab键
python3不允许同时使用空格和tab键

1.3 行最大长度

所有行限制最大字符数为79
注释、字符串等文本行最大字符数限制72
如果团队内达成一致认识，可以将代码行最大长度扩大到99，注释行仍然限制72

一行代码过长时优先通过小括号，方括号，花括号来换行，而不是反斜线的方式

# 推荐做法
  def methond_to_show_code_set_in_multiline_with_bracket(first_paramp="",
                                                    second_param="",
                                                    third_param=""):
     pass
         
# 不推荐做法
 def methond_to_show_code_set_in_multiline_with_bracket(first_paramp="",\
                                                    second_param="",\
                                                    third_param=""):
     pass

1.4 在二元运算符之前还是之后换行呢？

在很长的表示式中如果想换行推荐在二元操作符之前换行

# 推荐做法
income = (gross_wages
      + taxable_interest
      + (dividends - qualified_dividends)
      - ira_deduction
      - student_loan_interest)

# 不推荐做法
income = (gross_wages +
      taxable_interest +
      (dividends - qualified_dividends) -
      ira_deduction -
      student_loan_interest)

1.5 空行

文件顶级的类或者函数定义的前后需要使用两个空行
类中方法定义前后使用一个空行

# 注释

def func1():
    pass


class Demo1():

    def method1(self):
    pass

    def method2(self):
    pass


def func2():
    pass


class Demo2():
    pass

1.6 源文件编码

文件中不应有编码声明，默认均以UTF-8编码

1.7 imports

不同的包在不同的行导入，不推荐一行导入多个包
一行可以导入同一个包中的多个模块或类
导入总是文件的顶部，在模块注释和文档字符串之后，在模块的全局变量和常量之前
导入应该按照如顺序导入，在每一组中间需要加入空行
标准库导入
第三方库导入
本地应用库导入
推荐使用绝对路径导入，可读性更好

避免使用通配符导入，如from xxx import *

# 推荐做法
import os
import sys
from subprocess import Popen, PIPE

from flask import Flask

# 不推荐做法
import os,sys
from subprocess import Popen, PIPE
from flask import Flask

1.8 模块级的魔法函数名

像 __all__,__author__,__version__等模块级的魔法函数，应该放在文档字符串后面，并且在除了
from future import xxx 语句以外其他的import语句之前，如：

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

二、字符串引号

单引号或者双引号均可以，只需要代码风格保持一致即可
三引号推荐使用三个双引号

三、表达式和语句块中的空格

3.1 不能忍受的

下列情况下不允许使用空格

紧跟在小括号、中括号、大括号后
紧贴在逗号，分号或者冒号之前，注意在切片中的冒号，两边需要有相同数量的空格，当切片参数省略时，空格也必须省略
紧贴在函数参数的左括号之前
紧贴索引或者切片的左括号之前

为了和赋值运算符对齐，在赋值运算符之前加多个空格

# 推荐做法
spam(ham[1], {eggs: 2})
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]
spam(1)
dct['key'] = lst[index]
x = 1
y = 2
long_variable = 3

# 不推荐做法
spam( ham[ 1 ], { eggs: 2 } )
if x == 4 : print x , y ; x , y = y , x
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : upper]
ham[ : upper]
spam (1)
dct ['key'] = lst [index]
x             = 1
y             = 2
long_variable = 3

3.2 其他建议

避免在尾部添加空格
总是在二元运算符两天各添加一个空格
如果使用具有不同优先级的运算符，推荐在具有最低优先级的运算符周围加空格，但是最多使用一个空格，

并且在二元运算符两边使用相同数量的空格

在函数调用或定义中使用默认值或者指定参数的时候，=前后不要使用空格
功能型注释应该使用冒号的一般性原则，并且在使用->的时候前后需要使用空格
当给有类型备注的参数赋值的时候，在=两边添加空格，注意这里仅针对有类型备注说明的

复合语句（一行中有多个语句）通常是不允许的

# 推荐做法
 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 munge(input: AnyStr): ...
 def munge() -> AnyStr: ...
 def munge(sep: AnyStr = None): ...
 def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
 if foo == 'blah':
     do_blah_thing()
 do_one()
 do_two()
 do_three()

# 不推荐做法
 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 munge(input:AnyStr): ...
 def munge()->PosInt: ...
 def munge(input: AnyStr=None): ...
 def munge(input: AnyStr, limit = 1000): ...
 if foo == 'blah': do_blah_thing()
 do_one(); do_two(); do_three()

四、注释

4.1 注释说明：

与代码相矛盾的注释比没有注释更糟糕，当代码更改时，优先更新对应的注释
注释应该是完整的句子，如果一个注释是一个短语或句子，它的第一个单词应该大写
注释中永远不要改变标识符的大小写
如果注释很短，结尾的句号可以省略
块注释一般由完整句子的一个或者多个段落组成，并且每句话结束有个句号
在句尾结束的时候应该使用两个空格
在非英语国家的python程序员，请使用英语写注释，除非120%的确定你的代码不会被其他语言的人阅读

4.2 块注释

块注释通常适用于跟随他们的某一些（或全部）代码，并缩进到代码相同的级别
块注释的每一行开头使用一个#和一个空格（除非注释内部缩进文本）
块注释内部的段落通过只有一个#的空行分隔

4.3 行注释

有节制的使用行注释
行注释是与代码同行的注释，行注释和代码之间至少两个空格分隔
行注释由一个#和一个空格开始

4.4 文档注释

要为所有的公共模块、函数、类以及方法编写文档说明，非公共的方法没有必要，但是应该有一个描述方法具体作用的注释，这个注释在def那一行之后
多行文档注释的结尾的三个引号需要独自成一行
对于单行的文档注释，结尾的三个引号应该和文档在一行

五、命名规范

5.1 最重要的原则

暴露给用户的api接口的命名，应该遵循反映使用场景而不是实现的原则

5.2 命名风格

lower_case_with_underscores 使用下划线分割的小写字母
CapitalizadWords 驼峰命名法
mixedCase 第一个单词的首字母小写
lowercase 小写字母
UPPERCASE 大写字母
UPPER_CASE_WITH_UNDERSCORES 使用下划线分割的大写字母
b 单个小写字母
B 单个大写字母
Capitalized_Words_With_Underscores（巨丑）

5.3 命名约定

5.3.1 应避免的命名

永远不要使用实木'l'（小写的L），‘O’（大写的o）或者I（大写的i）作为单字符变量名

5.3.2 包和模块命名

模块名应该用简短全小写的名字，如果为了提升可读性，下划线也是可以的
包名也应该使用简短全小写的名字，不建议使用下划线

5.3.3 类命名

类名一般使用首字母大写的约定

5.3.4 异常命名

异常一般都是类，所以使用类名约定，此外需要在异常名后加上‘Error’后缀

5.3.5 全局变量命名

全局变量名应该小写，如果为了提高可读性，可以使用下划线

5.3.6 函数名命名

函数名应该小写，如果为了提高可读性，可以使用下划线

5.3.7 函数和方法的参数命名

和普通的变量名一致，即小写，如果为了提高可读性，可以使用下划线

5.3.8 方法名和实例变量命名

方法名和函数名一致，可以使用下划线
非公有方法名以单下划线开头
实例变量使用单下划线开头

5.3.9 常量命名

通过下划线分割的全大写字母，如 MAX_OVERFLOW

5.3.10 继承设计

公共属性不应该有前缀下划线
如果不确定一个属性时公有还是非公有，选择非公有，因为非公有转换为公有比

反过来简单的多

对于单一的公有属性数据，最好直接暴露它的变量名
不希望子类使用的属性，使用双下划线开头

5.4 公共和内部接口

为了更好的支持自省，模块应该使用__all__，属性显式的在他们的公共API中声明
即使通过__all__设置过，内部接口（包，模块，类，方法，属性或其他名字）依然需要单个下划线前缀

六、编码建议

代码应该用不损害其他Python实现的方式编写
和像None这样的单例对象进行比较的时候应该使用is 或者is not ，永远不要使用等号运算符
始终使用def表达式，而不是通过赋值语句将lambda表达式绑定到一个变量上
从Exception继承异常，而不是BaseException，直接继承BaseException的异常适用于几乎不用来捕捉的异常
返回的语句保持一致
当代码片段局部使用了某个资源的时候，使用with 表达式来确保这个资源使用完后被清理干净
使用 ”.startswith() 和 ”.endswith() 代替通过字符串切割的方法去检查前缀和后缀
对象类型的比较应该用isinstance()而不是直接比较type
不要用 == 去和True或者False比较

# 推荐：
if foo is not None:
def f(x): return 2*x

# 不推荐：
if not foo is None:
f = lambda x: 2*x

Python----Python编码规范