python开发规范(转载)
转载自http://www.cnblogs.com/wangcp-2014/p/4838952.html
目录
-
代码布局
1.1 缩进
1.2 表达式和语句中的空格
1.3 行的最大长度
1.4 空行
1.5 编码
-
语句
2.1 标准头部...
2.2 导入（import）...
2.3 赋值...
2.4 分支和循环...
-
注释
3.1 注释块...
3.2 行内注释...
3.3 文档字符串...
3.4 版本注记...
3.5 模块注释...
3.6 函数和方法注释...
3.7 类注释...
-
命名约定...
4.1 说明：命名约定...
4.2 模块名...
4.4 类名...
4.5 异常名...
4.6 变量、常量、全局变量名...
4.7 函数名...
4.8 方法名和实例变量...
4.9 特定的命名方式...
-
继承的设计...
-
设计建议...
代码布局
1.1 缩进
推荐以4个空格作为一个缩进层次。
1.2 表达式和语句中的空格
1.2.1 前导空格（缩进）
最流行的Python缩进方式是仅使用空格，其次是仅使用制表符。对于新的项目，应该仅使用空格而不是制表符。
1.2.2 非前导空格
非前导空格在Python代码中没有意义，但适当地加入非前导空格可以增进代码可读性：
（1）在二元算术、逻辑运算符前后加空格，如：
a = b + c
if a and b:
pass
（2）在一元前缀运算符后不加空格，如：
if !flg:
pass
（3）“:”用在行尾时前后皆不加空格，如分支、循环、函数和类定义语言；用在非行尾时后端加空格，如dict对象的定义：
d = {'key': 'value'}
（4）括号（含圆括号、方括号和花括号）前后不加空格，如：
do_something(arg1, arg2)
（5）逗号后面加一个空格，前面不加空格。
1.3 行的最大长度
每行的最大长度不得超过80个字符的标准。超过80个字符的，建议使用以下方式将单个长行折叠成多个短行：
（1）为长变量名换一个短名，如：
错误写法：
this.is.a.very.long.variable_name = this.is.another.long.variable_name
正确写法：
variable_name1 = this.is.a.very.long.variable_name
variable_name2 = this.is.another.variable_name
variable_name1 = variable_name2
（2）在括号（包括圆括号、方括号和花括号）内的分隔符后换行，如：
示例：
class Edit(Base):
def __init__(self, parent, width,
font = FONT, color = BLACK, pos = POS, style = 0): # 注意：此行与上一行保持同样缩进
pass
（3）在长行加入续行符强行断行，断行的位置应在操作符前，如：
if color == WHITE or color == BLACK \
or color == BLUE: # 注意：换行与首行保持同样的缩进（或均不缩进）
do_something(color)
1.4 空行
输入空行时，一般遵循以下原则：
（1）在import不同种类的模块间加空行；
（2）顶层函数和类的定义之间加空行；
（3）在类与类的定义之间加空行；
（4）在函数与函数的定义之间加空行；
（5）在class定义行和其第一个方法定义之间加空行；
（6）在函数中的逻辑段落间加空行，即把相关的代码紧凑写在一起，作为一个逻辑段落，段落间以空行分隔。
1.5 编码
所有的Python脚本文件都应在文件头标上#-- coding:utf8 -- ；用于设置编辑器，默认保存为utf8格式：
#-*- coding:utf8 -*-
语句
2.1 标准头部
一般情况下使用如下标准头部语句：
#!/usr/bin/python
如果需要使用自定义的Python编译环境，可使用类似如下的头部语句：
#!/usr/bin/env python2.7
说明：该行语句的作用是帮助内核找到Python解释器，但通常在Python导入模块时被忽略；只有直接执行单个文件时，该语句才是必要的。
2.2 导入（import）
2.2.1 通常应该在单独的行中导入（import），例如“正确写法1”；若需要在一行中从一个模块导入多个类，可参照“正确写法2”：
错误写法：
import sys, os
正确写法1：
import sys
import os
正确写法2：
from types import StringType, ListType
2.2.2 导入语句的位置及导入顺序
通常将import语句放置在文件的顶部，仅在模块注释和文档字符串之后，在模块的全局变量和常量之前。导入语句应该有顺序地成组安放：
（1）首先，导入标准库（内置模块）；
（2）其次，导入第三方模块（引用的第三方包）；
（3）最后，导入自己开发的项目中的其他模块；
在每组导入之间放置一个空行。
2.2.3. 导入类的方法
从一个包含类的模块中导入类时，通常可以写成这样：
示例：
from MyClass import MyClass
from foo.bar.YourClass import YourClass
如果上述写法导致了本地名字冲突，那么就这样写：
示例：
import MyClass
import foo.bar.YourClass
然后使用MyClass.MyClass和foo.bar.YourClass.YourClass方式即可。
2.3 赋值
对于赋值语言，主要是不要做无谓的对齐，如：
错误写法：
a = 1
var = 2
fn = callback_function
正确写法：
a = 1
var = 2
fn = callback_function
2.4 分支和循环
各种分支和循环语句不要写成一行，如：
错误写法：
if !flg: pass
for i in xrange(10): print i
正确写法：
if !flg:
pass
for i in xrange(10):
print i
注释
代码修改时，始终优先更新注释。注释应该是完整的句子，如果注释是一个短语或句子，首字母应该大写，除非他是一个以小写字母开头的标识符（如果以中文注释可忽略此要求）。
3.1 注释块
注释块通常用于跟随着一些代码并和这些代码有着相同的缩进层次。注释块中每行均以“#”和一个空格开始。注释块内的段落间以仅含单个“#”的行分割。注释块上下方最好各有一空行。
3.2 行内注释
行内注释是和语句在同一行的注释。行内注释应该至少用两个空格和语句分开，且应该以“#”和单个空格开始，如：
示例：
x = x + 1 # Increment x
如果语意很明了，那么行内注释则不必要。
3.3 文档字符串
为所有公共模块、函数、类和方法编写文档字符串。文档字符串对非公开的方法不是必要的，但应该有一个注释描述这个方法的作用。这个注释应该在“def”行之后。
一定注意，多行文档字符串结尾的"""应该单独成行，例如：
示例：
"""Return a foobang
Optional plotz says to frobnicate the bizbaz first
"""
对单行的文档字符串，结尾的"""在同一行也可以，例如：
"""Return a foobang"""
3.4 版本注记
版本注记可以参照如下示例代码：
示例：
__version__ = "$Revision: 1.4 $"
这行应该包含在模块的文档字符串之后，所有代码之前，上下用一个空行分割。
3.5 模块注释
每个模块注释都应该包含下列项，依次是：
（1）版权声明；
（2）模块注释内容，包括模块描述、模块中的类和方法的描述、版本及维护信息等；
（3）作者声明，标识文件的原作者；
示例：
# Copyright (C), 2010-2013, China Standard Software Co., Ltd.
"""
FileName: Test.py
Author: fei.liu
Version: 0.1
Date: 2013-02-27
Description: 用一行文字概述模块或脚本，用句号结尾。
ClassFoo: 一行概述该模块中的类的用途。
functionBar(): 一行概述该模块中的函数的用途。
History: /* 历史修改记录 */
<Author> <Date> <Version> <Desc>
fei.liu 2013-03-04 1.0 Release
"""
__authors__ = [
'"John Smith" <johnsmith@example.com>',
'"Joe Paranoid" <joeisgone@example.com>',
]
3.6 函数和方法注释
任何函数或方法都需要一个文档字符串，对于任何外部可访问的函数或方法，文档字符串尤为重要。
文档字符串应该包含函数的作用，以及参数、输入和输出的详细描述：
（1）Args：输入参数的具体描述；如果参数要求特定的数据类型或者设置了参数的默认值，那么应该在文档字符串中明确说明；
（2）Returns：输出（返回）数据的具体描述；
（3）Raises：应该列出该函数可能触发的所有异常；
示例：
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""取出表格中的多行内容
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table rowto fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data fetched.
Each row is represented as a tuple of strings. For example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass
3.7 类注释
类定义下方必须有一个用于描述该类的文档字符串（docString）。如果类中有公共属性（Attributes），那么文档字符串中应该说明这些公共属性的意义。
示例：
class SampleClass(object):
"""Summary of class here.
Longer class information....
Longer class information....
Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
"""
def __init__(self, likes_spam=False):
"""Inits SampleClass with blah."""
self.likes_spam = likes_spam
self.eggs = 0
def public_method(self):
"""Performs operation blah."""
命名约定
4.1 说明：命名约定
禁止使用字符“l”、“O”或“I”作为单字符的变量名。在某些字体中无法将这些字符与数字1和0区分开。
4.2 模块名
模块名应该是不含下划线的、简短的、全小写的名字；对于默认仅在包（Packages）内使用的模块，可以加一个下划线前缀，如：
示例：
module.py
_internal_module.py
4.4 类名
类名使用CapWords约定（单词首字母大写，不使用下划线连接单词，也不加入C、T等前缀）；内部使用的类需要在名称前加一个前导下划线，如：
示例：
class ThisIsAClass(object):
pass
class _ThisIsAClass(object):
pass
4.5 异常名
异常名使用CapWords命名规则（单词首字母大写，不使用下划线连接单词）。
4.6 变量、常量、全局变量名
Python一般通过“from M import *”来从模块中导入相关内容（变量、类、函数等），必须用一个下划线作全局变量（内部函数或类）的前缀防止其被导出（exporting）。
4.6.1. 常量
常量名的所有字母均大写，由下划线连接各个单词，如：
示例：
WHITE = 0XFFFFFF
THIS_IS_A_CONSTANT = 1
4.6.2. 变量
（1）变量名全部小写，由下划线连接各个单词，如：
示例：
color = WHITE
this_is_a_variable = 1
（2）不论是类成员变量还是全局变量，均不使用m或g前缀。私有类成员使用单一下划线前缀标识；
（3）变量名不应带有类型信息，因为Python是动态类型语言；如iValue、names_list、dict_obj等都是不好的命名。
4.6.3. 全局变量
必须用一个下划线作为全局变量的前缀防止其被导出。
4.7 函数名
函数名应该为小写，可用下划线风格单词以增加可读性。
4.8 方法名和实例变量
大体上和函数命名规则相同：通常使用小写单词，必要时用下划线分隔增加可读性。
如果是不打算对外公开的内部方法和实例，需要在名称开头使用一个前导下划线。
使用两个前导下划线以表示类私有成员的名字。通常双前导下划线仅被用于避免含子类的类中的属性名冲突。
4.9 特定的命名方式
主要是指__xxx__形式的系统保留字命名法。项目中也可以使用这种命名，它的意义在于这种形式的变量是只读的，这种形式的类成员函数尽量不要重载。如：
示例：
class Base(object):
def __init__(self, id, parent = None):
self.__id__ = id
self.__parent__ = parent
def __message__(self, msgid):
# ...
其中__id_、__parent__和__message__都采用了系统保留字命名法。
继承的设计
始终要确定一个类中的方法和实例变量是否要被公开。通常，永远不要将数据变量公开，除非你实现的本质上只是记录，人们总是更喜欢为类提供一个函数的接口来实现数据变量的修改。
同样，确定你的属性是否应为私有的。私有和非私有的区别在于：前者永远不会被用在一个派生类中，而后者可能会。你应该在大脑中就用继承设计好了你的类：（1）私有属性必须有两个前导下划线，无后置下划线；（2）非公有属性必须有一个前导下划线，无后置下划线；（3）公共属性没有前导和后置下划线，除非它们与保留字冲突，在此情况下，单个后置下划线比前置或混乱的拼写要好，例如：class_优于klass。
设计建议
单个元素（singletons）的比较，如None应该使用“is”或“is not”。当你本意是“if x is not None”时，对写成“if x”要小心。例如当你测试一个默认为None的变量或参数是否被设置为其它值时，这个其它值也许在布尔上下文（Boolean context）中是False。
基于类的异常总是好过基于字符串的异常。模块和包应该定义它们自己的域内特定的基异常类，基类应该是内建的Exception类的子类，还始终包含一个类的文档字符串。例如：
示例：
#!/usr/bin/Python
class(Exception)：
"""Base class for errors in the email package."""
MessageError
使用字符串方法（methods）代替字符串模块，除非必须向后兼容Python 2.0以前的版本。字符串方法总是非常快，而且和unicode字符串共用同样的API（应用程序接口），在检查前缀或后缀时避免对字符串进行切片。用startswith()和endswith()代替，因为这样出现错误的机率更小。例如：
错误写法：
if foo[:3] == 'bar':
正确写法：
if foo.startswith('bar'):
特殊情况下，如果你的代码必须工作在Python 1.5.2，对象类型的比较应该始终用isinstance()代替直接比较类型，例如：
错误写法：
if type(obj) is type(1):
正确写法：
if isinstance(obj, int):
检查一个对象是否是字符串时，谨记它也可能是unicode字符串！在Python 2.3中，str和unicode有公共的基类basestring，所以你可以这样做：
if isinstance(obj, basestring):
在Python 2.2类型模块为此定义了StringTypes类型，例如：
#!/usr/bin/Python
from types import StringTypes
if isinstance(obj， StringTypes):
对序列（字符串、列表、元组）而言，使用空列表是false这个事实，因此“if not seq”或“if seq”比“if len(seq)”或“if not len(seq)”好。书写字符串文字时不要依赖于有意义的后置空格。这种后置空格在视觉上是不可辨别的，并且有些编辑器会将它们修整掉。不要用“==”来比较布尔型的值以确定是True或False（布尔型是Python2.3中新增的）：
错误写法：
if greeting == True:
正确写法：
if greeting:
