Python编程规范

Pylint

Pylint 是一个 Python 代码分析工具，它分析 Python 代码中的错误，查找不符合代码风格标准（Pylint 默认使用的代码风格是 PEP 8）和有潜在问题的代码。pylint不仅可以检测出代码中的错误，还能对代码质量进行检测。

Pylint在Linux下的安装 

1. 在 Linux 上，首先安装 Python 的包（高于版本 2.2），并在环境变量 $PATH 中添加 Python 可执行文件的路径。

2. 下载 Pylint、logilab-astng (version >= 0.14) 和 logilab-common (version >= 0.13) 的包 , 使用 tar zxvf *.tar.gz解压缩这些包。（logilab-astng 的最新包下载：http://www.logilab.org/856/   logilab-common 的最新包下载：http://www.logilab.org/848/   Pylint 的最新包下载：http://www.logilab.org/project/pylint）

3. 依次进入 logilab-astng、logilab-common 和 Pylint 解开的文件夹中，运行命令 Python setup.py install来安装。

4. 安装完成后，就可以通过 pylint [options] module_or_package来调用 Pylint 了。

5. pylint在Windows下的安装以及调试的例子可以参考：IBM Developer（原理比较详细）以及http://guozhiwei.iteye.com/blog/900453（着重例子）

编码

设置编辑器，默认保存为 utf-8 格式。

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

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

注释

业界普遍认同 Python 的注释分为两种的概念:一种是由 # 开头的“真正的”注释，另一种是 docstrings。前者表明为何选择当前实现以及这种实现的原理和难点，后者表明如何使用这个包、模块、类、函数（方法），甚至包括使用示例和单元测试。

坚持适当注释原则。对不存在技术难点的代码坚持不注释，对存在技术难点的代码必须注释。但与注释不同，推荐对每一个包、模块、类、函数（方法）写 docstrings，除非代码一目了然，非常简单。

格式

1. 缩进：Python 依赖缩进来确定代码块的层次，行首空白符主要有两种：tab 和空格，但严禁两者混用；采用4个空格的TAB缩进（VIM等编辑器中设置）

2. 空格：空格在 Python 代码中是有意义的，因为 Python 的语法依赖于缩进，在行首的空格称为前导空格。在这一节不讨论前导空格相关的内容，只讨论非前导空格。非前导空格在 Python 代码中没有意义，但适当地加入非前导空格可以增进代码的可读性。

•  在二元算术、逻辑运算符前后加空格，如：

1 a = b + c

• “:”用在行尾时前后皆不加空格，如分枝、循环、函数和类定义语言；用在非行尾时两端加空格，如 dict 对象的定义：　　　

1 d = {'key' : 'value'}

• 括号（含圆括号、方括号和花括号）前后不加空格，如：

1 do_something(arg1, arg2)

• 逗号后面加一个空格，前面不加空格；　　

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

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

4. 断行：本规范坚持行的最大长度不得超过 78 个字符的标准。折叠长行的方法有以下几种方法：

• 为长变量名换一个短名，如：

1 #长变量名
2 this._is.a.very.long.variable_name = this._is.another.long.variable_name
3 #应该改为
4 variable_name1 = this._is.a.very.long.variable_name  
5 variable_name2 = this._is.another.variable_name  
6 variable_name1 = variable_name2s

• 在括号（包括圆括号、方括号和花括号）内换行，如：

 1 class Edit(Widget):  
 2   def __init__(self, parent, width,  
 3       font = FONT, color = BLACK, pos = POS, style = 0): # 注意：多一层缩进(换行后两个TAB键)
 4     pass 
 5 
 6 # 或者是下面的这种形式
 7 very_very_very_long_variable_name = Edit(parent,  
 8   width,  
 9   font,  
10   color,  
11   pos) # 注意：多一层缩进  
12 do_sth_with(very_very_very_long_variable_name)  

• 如果行长到连第一个括号内的参数都放不下，则每个元素都单独占一行：　　

1 very_very_very_long_variable_name = ui.widgets.Edit(  
2   panrent,  
3   width,  
4   font,  
5   color,  
6   pos) # 注意：多一层缩进  
7 do_sth_with(very_very_very_long_variable_name) 

• 在长行加入续行符强行断行，断行的位置应在操作符前，且换行后多一个缩进，以使维护人员看代码的时候看到代码行首即可判定这里存在换行，如：　

1 if color == WHITE or color == BLACK \  
2     or color == BLUE: # 注意 or 操作符在新行的行首而不是旧行的行尾，上一行的续行符不可省略  
3   do_something(color);  
4 else:  
5   do_something(DEFAULT_COLOR);  

5. 命名：一致的命名可以给开发人员减少许多麻烦，而恰如其分的命名则可以大幅提高代码的可读性，降低维护成本。

• 常量名所有字母大写，由下划线连接各个单词。
• 变量名全部小写，由下划线连接各个单词：不论是类成员变量还是全局变量，均不使用 m 或 g 前缀。私有类成员使用单一下划线前缀标识，多定义公开成员，少定义私有成员；变量名不应带有类型信息，因为 Python 是动态类型语言。如 iValue、names_list、dict_obj 等都是不好的命名。
• 函数名的命名规则与变量名相同。
• 类名单词首字母大写，不使用下划线连接单词，也不加入 C、T 等前缀。
• 模块名全部小写，对于包内使用的模块，可以加一个下划线前缀。
• 包的命名规范与模块相同。
• 缩写：命名应当尽量使用全拼写的单词，缩写的情况有如下两种：①常用的缩写，如 XML、ID等，在命名时也应只大写首字母 ②命名中含有长单词，对某个单词进行缩写。这时应使用约定成俗的缩写方式，如去除元音、包含辅音的首字符等方式
• 特定的命名方式：主要是指 __xxx__ 形式的系统保留字命名法。项目中也可以使用这种命名，它的意义在于这种形式的变量是只读的，这种形式的类成员函数尽量不要重载。

 1 # 命名例子
 2 
 3 # 常量
 4 WHITE = 0xffffffff  
 5 THIS_IS_A_CONSTANT = 1
 6 
 7 # 变量
 8 color = WHITE  
 9 this_is_a_variable = 1  
10 
11 # 类
12 class ThisIsAClass(object):  
13   pass
14 
15 # 模块
16 module.py  
17 _internal_module.py  （内部模块）
18 
19 # 缩写
20 class XmlParser(object):pass
21 # 去元音：fuction->fn  text->txt
22 
23 # 特定命名
24 class Base(object):  
25   def __init__(self, id, parent = None):  
26     self.__id__ = id  
27     self.__parent__ = parent  
28   def __message__(self, msgid):  
29     # …略 

6. 语句：对于import语句：必须遵循import 的次序，先 import Python 内置模块，再 import 第三方模块，最后 import 自己开发的项目中的其它模块；这几种模块中用空行分隔开来；一条 import 语句 import 一个模块；不要使用 from module import *，除非是 import 常量定义模块或其它你确保不会出现命名空间冲突的模块；当从模块中 import 多个对象且超过一行时，使用如下断行法（此语法 py2.5 以上版本才支持）：

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

7. 已有代码：　　

• 对于项目中已有的代码，可能因为历史遗留原因不符合本规范，应当看作可以容忍的特例，允许存在；但不应在新的代码中延续旧的风格。
• 对于第三方模块，可能不符合本规范，也应看作可以容忍的特例，允许存在；但不应在新的代码中使用第三方模块的风格。
• ab 与空格混用的缩进是'''不可容忍'''的，在运行项目时应使用 -t 或 -tt 选项排查这种可能性存在。出现混用的情况时，如果是公司开发的基础类库代码，应当通知类库维护人员修改；第三方模块则可以通过提交 patch 等方式敦促开发者修正问题。