Python 编码规范

一、文件编码

所有的 Python 脚本文件都应在文件头部指定如下标识或其兼容格式的标识：

# -*- coding: utf-8 -*-

二、注释

注释分为两类，以 # 开头的“真正的”注释，和 docstring。前者一般用于说明实现的原理及难点，后者用于说明使用方法、示例以及单元测试。

坚持适当注释原则。对不存在技术难点的代码坚持不注释，对存在技术难点的代码必须注释。

三、格式

注释

以 # 开头的注释，在 # 符号后加空格，再写注释内容。对于行内注释，在语句后空出至少2格，再加注释部分。

缩进

Python 严格依赖缩进来确定代码块的层次。可以使用空格或者 Tab 来缩进代码。一般地，一个缩进层次采用 4 个空格。

空格

代码中适当加入空格可增强代码的可读性。

(1) 在二元算术、逻辑运算符、赋值运算符前后加空格：

a = b + c

算术运算符左右一般要加空格；但复杂表达式中，优先级高一些的部分，算术运算符左右不加空格：

x = x*2 - 1  # 乘号的优先级高
c = (a+b) * (a-b)  # 括号部分的优先级高一些

(2) 冒号（:）用在行尾时前后皆不加空格，如分支、循环、函数和类定义语言；用在非行尾时右边加空格，如 dict 对象的定义：

d = {'key': 'value'}

(3) 括号（含圆括号、方括号和花括号）前后不加空格，作为分隔符的逗号后加空格：

do_something(arg1, arg2)

函数定义及调用时的形参赋值，等号左右不加空格：

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

(4) 逗号后面加一个空格，前面不加空格。

空行

适当的空行有利于增加代码的可读性，加空行可以参考如下几个准则：

在类、函数的定义间加空行
在 import 不同种类的模块间加空行
在函数中的逻辑段落间加空行，即把相关的代码紧凑写在一起，作为一个逻辑段落，段落间以空行分隔

断行

一般地，行的最大长度不超过 78 个字符。可以使用括号（包括圆括号、方括号、花括号）和反斜线来断行，在断行后增加一个缩进。

四、命名

常量

常量名所有字母大写，由下划线连接各个单词。

APP_REQUEST_TIMEOUT = 600

变量

变量名全部小写，由下划线连接各个单词
私有类成员使用单一下划线前缀标识
变量名不应带有类型信息，因为 Python 是动态类型语言。如 iValue、names_list、dict_obj 等都不是好的命名

函数

函数名的命名规则与变量名相同。

类

类名采用 Pascal 命名法。单词首字母大写，不使用下划线连接单词，也不加入 C、T 等前缀。

模块

模块名全部小写，对于包内使用的模块，可以加一个下划线前缀。注意不要与内置的模块名重复，否则会导致内置模块不可用。

包

包的命名规范与模块相同。

五、语句

import

import 的次序，先 import Python 内置模块，再 import 第三方模块，最后 import 自己开发的项目中的其它模块；用空行分隔这几类模块。

一条 import 语句只导入一个模块。

当从模块中 import 多个对象且超过一行时，使用如下断行法（此语法 py2.5 以上版本才支持）：

from module import (obj1, obj2, obj3, obj4, 
    obj5, obj6)

不要使用 from module import *，除非是 import 常量定义模块或其它你确保不会出现命名空间冲突的模块。

赋值

不要做无谓的对齐：

a        = 1                  # 这是一个行注释
variable = 2                  # 另一个行注释
fn       = callback_function  # 还是行注释

没有必要做这种对齐，原因有两点：一是这种对齐会打乱编程时的注意力，大脑要同时处理两件事（编程和对齐）；二是以后阅读和维护都很困难，因为人眼的横向视野很窄，把三个字段看成一行很困难，而且维护时要增加一个更长的变量名也会破坏对齐。直接这样写为佳：

a = 1 # 这是一个行注释  
variable = 2 # 另一个行注释  
fn = callback_function # 还是行注释

分支和循环

(1) 不要写成一行，如：

if not flg: pass

应该这样：

if not flg:  
    pass

(2) 条件表达式的编写应该足够 pythonic，如以下形式的条件表达式是拙劣的：

if len(alist) != 0: do_something()
if s != "": do_something()
if var != False: do_something()