Python代码编写规范

前言：

为了保证代码的易读性，可维护性，稳定性，以及提高脚本的美观度，运行性能，并提前发现一些隐藏的BUG，特制定这一系列通用的规则来统一大家的编写风格，各自业务组可以制定更详细的规则，如模块的划分，引用关系等。

Python之禅：

优美胜于丑陋（Python 以编写优美的代码为目标）
明了胜于晦涩（优美的代码应当是明了的，命名规范，风格相似）
简洁胜于复杂（优美的代码应当是简洁的，不要有复杂的内部实现）
复杂胜于凌乱（如果复杂不可避免，那代码间也要保持接口简洁）
扁平胜于嵌套（优美的代码应当是扁平的，不能有太多的嵌套）
间隔胜于紧凑（优美的代码有适当的间隔，不要奢望一行代码解决问题）
可读性很重要（优美的代码是可读的）
即便假借特例的实用性之名，也不可违背这些规则（这些规则至高无上）
如果你无法向人描述你的方案，那肯定不是一个好方案。

一、代码排版规范

强制要求：
1、缩进。统一使用4个空格的缩进，不要使用Tab，更不要混合使用Tab和空格。
2、顶层类和函数，以及调试入口与最近的代码空两行；类中的方法定义之间空一行。
3、导入模块结束后空两行开始定义全局变量，全局变量定义后空两行开始定义顶层类或函数。
4、不要一行import多个库，比如import os, sys。
5、import库的顺序为：标准库、开源第三方库、自定义库。
6、禁止从模块import *的操作 。
7、不要导入没有使用到的库。
8、 圆括号, 中括号和花括号中每项的换行不要多此一举地使用换行符
9、调试代码必须放在if name == 'main’条件下。

建议：
1、每行最大长度可放宽到128，为了内容的连贯已读性，超过一两个字符时不必换行。
2、换行操作符“/”后紧跟回车。
3、当要使用不同模块下的相同函数名时，采用import XX，调用时加模块前缀。
4、定义字典时按照层级进行四空格缩进。
5、模块的内部方法和变量的定义排在前，对外裸露的方法和变量的定义排在后。

二、空格使用规范

强制要求：
1、各种括号(小括号，中括号，大括号)的前后不要加空格。
2、逗号、冒号前不要加空格，逗号和冒号用于分割项和映射关系时在逗号和冒 号后面空一格。
3、二元运算符、逻辑运算符、格式化符前后各加一个空格。
4、不要为了对齐增加多余的空格。
5、函数传参时各参数之间逗号后加1个空格，如func(1, a=2)。

建议：
1、行尾不要有多余空格。
2、注释内容的空格使用没有严格限制，以简洁美观性为准。

三、命名规范

强制要求：
1、全局变量和常量全部大写，其他类型的变量全部小写， 使用下划线分割单词。
2、模块命名不能跟已有的内置库和三方库重名，全部小写的方式， 使用下划线分割单词。
3、包命名不能跟已有的内置库和三方库重名，全部小写的方式， 使用下划线分割单词。
4、类的命名使用驼峰命名规则。如CapWords，模块内部使用的类命名加双下划线的私有属性标志，如：_CapWords。
5、函数名全部小写， 使用下划线分割单词。
6、各类变量名不能跟python内置关键字和方法重名。
7、不要使用拼音缩写，缩写要能体现主要信息，参考本文档最后的编程界约定俗成的缩写表

建议：
1、变量命名遵循形容词 + 名词 + 单复数方式，可以加后缀表名变量类型，如：name_list, data_dict, info_str。
2、模块，包，类等命名不应太长，一般小于20个字符。
3、函数名一般是动宾结构，以动词开头，长度一般小于40个字符。
4、全局变量尽量只在模块内有效，实现方法有两种，一是__all__ = [‘xx’]机制, 一种是变量加下划线，这样别人import *也不会导入，避免造成覆盖。

四、注释规范

强制要求：
1、模块注释：也称描述文档，使用两个"""，包含但不限于如下内容：使用场景，支持的功能，调用顺序，调用例子， 版本依赖，日期和作者。
2、代码块注释：在一段代码前增加的只有注释的多行。使用#开头，空一格后写内容。
3、行注释：在代码行后空2格写注释内容。比如：x = 1 # 从1开始。
4、类注释：使用两个"""，包含但不限于如下内容：使用场景，支持的功能，参数说明，调用顺序，调用例子。
5、函数注释：使用两个"""，包含但不限于如下内容：支持的功能，参数类型和作用， 返回值。
6、模块内用作对外提供接口的函数必须加参数和返回值注释。
7、浅显的操作不要加注释，如打开文件，关闭文件等。

建议：
1、少使用行注释，理论上会拖累解释器执行速度。
2、为公共的模块、函数、类写描述文档。如下图所示：

3、块注释：代码中那些技巧性的部分，如果你在代码评审的时候必须要解释一下的, 那么你应该编写时就给它写注释，对于复杂的操作，应该在其操作开始前写上若干行注释，且块注释后面空一行再跟代码块。
4、实际业务中，函数和类的注释建议也著名开发人员姓名或工号。

五、语法规范

强制要求：
1、在文件头必须加编码申明：# -- coding: utf-8 --，为了代码在python2也能运行。
2、不要使用python2支持，而在python3已经淘汰的内置方法，如has()等。
3、不要将多句语句写在同一行，如if/for/while语句中，即使执行语句只有一句，也必须另起一行。
4、没有用到的过程变量用下划线修饰，如：for _k, v in items。
5、正式发布的代码应该去掉print语句，可采用公共的打印方法，发布时控制公共方法不打印。

建议：
1、在字符串拼接时，‘+’在CPython中效率很高，但是Jython中却非常低，所以推 荐用.join()。
2、尽可能使用is或is not 取代等于’==’，比如if x is not None。
3、异常捕获try的代码只放有可能出错的代码行。
4、while循环中每次循环加下sleep()，以便CPU切换其他任务来执行，避免一直占 用CPU做无用功。
5、字符串使用startswith()和endswith()代替切片进行前缀或后缀的检查。比如
6、Yes: if foo.startswith(‘bar’):优于
No: if foo[:3] == ‘bar’:
7、使用isinstance()比较对象的类型。比如
Yes: if isinstance(obj, int): 优于
No: if type(obj) is type(1):
8、判断序列空或不空，用如下规则
Yes: if not seq:
if seq:
优于
No: if len(seq):
if not len(seq):
9、避免使用晦涩难懂的语法，如循环再套匿名函数等。

六、常见英文缩写

英文 缩写 汉语意思
develop dev 开发
block blk 阻塞
memory mem 内存(一般用在全局或堆)
allocate alloc 分配
utility util 多功能
file pointer fp 文件句柄
extent ext 扩展
resource res 源
destination dst 目的
event evt 事件
connect conn 连接
config cfg 配置
server srv 服务
address addr 地址
request req 请求
buffer buf 内存（一般用在局部或栈）
cache cach 缓存
response resp 回复
operation opt 操作
option opt 选项
project proj 项目
profession pro 高级的
information info 信息
value val 值
lenght len 长度
collection col 收集
column col 列
array ary 数组
iterator itr 迭代
source src 源
include inc 包括
decline dec 减少/下降
function func 功能/函数
action act 触发/执行
execute exec 执行
argument arg 参数
signal sig 信号
single sgl 单个
error err 错误
field field 片
property prop 特性
defines defs 明确
object obj 对象
system sys 系统
message msg 消息
document doc 文档
application app 应用
process proc 进程
dispatch disp 发送
internet inet 网络
context ctx 背景/描述
receive recv 接收
number num 数量
directory dir 目录
dictionory dict 字典
protocol proto 协议
index idx 索引
modify mod 修改
window wnd 窗口
button btn 按钮
table tbl 盒子
label lbl 标签
Image img 图片
Sprite sp 小精灵
text tex 文本
transform trans 转换
convert conv 转换
animation anim 动画
material mat 原料
vecter vec 媒介
position pos 位置
callback cb 回调
compare cmp 比较
copy cpy 拷贝
second sec 秒/第二的
distro distro 发布
Subitem sub 子项