Python 编程规范 by @AKaras

by AKara 2010-08-07
微博：http://weibo.com/akaras
博客：http://blog.csdn.net/akara
邮箱：akaras(at)163.com
标签：网易 / MMORPG / 动作网游 / 项目运营 / 技术管理

---------------------------------------------------------------------

Python编程规范(for Python2.5 by AKara)

---------------------------------------------------------------------
源文件布局规范
---------------------------------------------------------------------

* 文件以utf-8编码保存。
* 文件第一行svn prop：# $Id$
* 文件第二行coding约定：# -*- coding: utf-8 -*-
* 选择4个空格进行缩进。
* 任一行代码长度不超过70列。
* 用 # 来注释。
* 非必要不写docstring。
* 中文注释。避免英文注释。

---------------------------------------------------------------------
命名规范
---------------------------------------------------------------------

* 变量：unix风格，小写加下划线，如：foo_bar。
* 常量：大写加下划线，如：ERROR_FOO_BAR。
* 函数：和 变量 一致，如：def foo_bar(): pass
* 类：大写C开头的驼峰法，如：CFooBar。(是的，与python lib风格不同)
* 模块：小写无下划线，如：foobar.py。
* 包：与 模块 一致。

* "私有化"命名约定：
一个且只一个下划线开始的命名。
表示本命名不能超过最近命名空间索引。
(不使用python的Private name mangling风格)

---------------------------------------------------------------------
比较规范
---------------------------------------------------------------------

* None：a is None
* int / str：a == 163 / a == "AKara"
* boolean：if a: / if not a:
* 杜绝比较不同类型的对象。

PS：虽然builtin的某些不同对象间是可按如下规则比较的：
(1)None最小
(2)Number次之
(3)其他类型比较类型字符串，如："dict" < "list"
即：None < Number(int/float) < dict < list < str < tuple
但Python后续版本并不保证维持这个规则。

---------------------------------------------------------------------
import规范
---------------------------------------------------------------------

* 所有import放在module最顶部。
* 每次import只导入一个module，如：
import akara
import evil
* 杜绝一次import多个module：import akara, evil
* 杜绝import * from a。
* 杜绝from a import b。
* 杜绝import a as b。
* 性质决定import先后：builtin > standard > engine > frozen > py。

---------------------------------------------------------------------
module规范
---------------------------------------------------------------------

* module分两种性质：(1)数据module (2)实现module
* 数据module：只包含数据定义和初始化。
* 实现module：只包含函数或类定义。
不包含任何import时便执行的赋值或初始化(比如name = CAkara())
* __load__()：执行module命名空间内的对象初始化的函数。
* __destroy__(): 执行module命名空间内的对象销毁的函数。
* 跨模块索引数据对象须考虑热更新。过早优化不必要，常用a.b.var索引。

---------------------------------------------------------------------
class规范
---------------------------------------------------------------------

* class必须直接或间接继承全局的gobject(非python内建的object)。
杜绝不继承任何基类的类定义：如 class CFoo: pass。
* 杜绝重载类的__del__方法来进行对象析构资源回收。
添加类的destroy方法统一销毁资源，并自行负责调用。
* 避免多继承。
* 总是让super来负责mro(Method resolution order)。

---------------------------------------------------------------------
其他建议
---------------------------------------------------------------------

* 安全性编码：tuple > list，frozenset > set，__debug__，assert。
* 迭代时优先考虑iter版本的内建函数或方法，如：
xrange / enumerate / zip / iterkeys / itervalues / iteritems ...
* 适当使用：list comprehension / generator / generator expression
decorator / __slots__ ...
* 少用properties。
* 用iter模式迭代大文件的读入。
* 考虑向下取整结果的整除操作符：//。
* 大量字符串链接请用 "".join(str_list) 。
* 精准捕捉异常。避免不指定Exception或指定Exception基类的except捕捉。
* 如果需常用popleft语义，用collections.deque代替list。
* 性能分析模块：hostshot > cProfile > profile。
* 善用weakref模块管理引用。
* -OO release。

---------------------------------------------------------------------
充分理解
---------------------------------------------------------------------

* 充分理解import a的path查找和介质载入处理过程。
* 充分理解python中的命名空间和对象的关系。
* 充分理解并合理利用clousure。
* 充分理解shallow copy & deep copy。
* 充分理解gc。
* import this。

---------------------------------------------------------------------
更多参考
---------------------------------------------------------------------

<<Style Guide for C Code>> http://www.python.org/dev/peps/pep-0007/
<<Style Guide for Python Code>> http://www.python.org/dev/peps/pep-0008/

---------------------------------------------------------------------