Python编码标准规范汇编.doc

Python 编码规范
遵循良好编码风格，可以有效提高代码可读性，减少出错几率和维护难度。在团队开发中，使用（尽量）统一编码风格，还可以减少沟通成本。
网上有诸多版本编码规范，基本上都是遵循 PEP8 规范：
· PEP 0008 – Style Guide for Python Code
· Google Python 风格指南
· Python Guide - Code Style
· Pocoo Styleguide
除了在编码时积极遵循规范，尚有诸多有用工具：
· IntelliJ IDEA 和 PyCharm 格式化代码功能
· Google 开源 Python 文献格式化工具：
· pyflakes，pylint 等工具及各种编辑器插件
本文内容重要摘自互联网上各种版本规范，由于公司有些小伙伴代码风格不太好，因此整顿了一份算是团队编码规范。
缩进
· 不要使用 tab 缩进
· 使用任何编辑器写 Python，请把一种 tab 展开为 4 个空格
· 绝对不要混用 tab 和空格，否则容易浮现 IndentationError
空格
· 在 list，dict，tuple，set，参数列表 , 背面加一种空格
· 在 dict  : 背面加一种空格
· 在注释符号 # 背面加一种空格，但是 #!/usr/bin/python  # 后不能有空格
· 操作符两端加一种空格，如 +, -, *, /, |, &, =
· 接上一条，在参数列表里 = 两端不需要空格
· 括号（(), {}, []）内两端不需要空格
空行
· function 和 class 顶上两个空行
· class method 之间一种空行
· 函数内逻辑无关段落之间空一行，不要过度使用空行
· 不要把各种语句写在一行，然后用 ; 隔开
· if/for/while 语句中，虽然执行语句只有一句，也要另起一行
换行
· 每一行代码控制在 80 字符以内
· 使用 \ 或 () 控制换行，举例：
· def foo(first，second，third，fourth，fifth,
· sixth，and_some_other_very_long_param):
· user = User.objects.filter_by(first=first，second=second，third=third) \
· .skip(100).limit(100) \
· .all()
·
· text = ('Long strings can be made up '
· 'of several shorter strings.')
命名
· 使用故意义，英文单词或词组，绝对不要使用汉语拼音
· package/module 名中不要浮现 -
· 各种类型命名规范：
Type
Public
Internal
Modules
lower_with_under
_lower_with_under
Packages
lower_with_under

Classes
CapWords
_CapWords
Exceptions
CapWords

Functions
lower_with_under()
_lower_with_under()
Global/Class Constants
CAPS_WITH_UNDER
_CAPS_WITH_UNDER
Global/Class Variables
lower_with_under
_lower_with_under
Instance Variables
lower_with_under
_lower_with_under (protected) or __lower_with_under (private)
Method Names
lower_with_under()
_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameters
lower_with_under

Local Variables
lower_with_under

import
· 所有 import 尽量放在文献开头，在 docstring 下面，其她变量定义上面
· 不要使用 from foo imort *
· import 需要分组，每组之间一种空行，每个分组内顺序尽量采用字典序，分组顺序是：
1. 原则库
2. 第三方库
3. 本项目 package 和 module
· 不要使用隐式相对导入（implicit relative imports），可是使用显示相对导入（explicit relative imports），如 from ..utils import validator，最佳使用全途径导入（absolute imports）
· 对于不同 package，一种 import 单独一行，同一种 package/module 下内容可以写一起：
· # bad
· import sys，os，time
·
· # good
· import os
· import sys
· import time
·
· # ok
· from flask import Flask，render_template，jsonify
· 为了避免也许浮现命名冲突，可以使用 as 或导入上一级命名空间
· 不要浮现循环导入(cyclic import)
注释
· 文档字符串 docstring，是 package，module，class，method，function 级别注释，可以通过 __doc__ 成员访问到，注释内容在一对 """ 符号之间
· function，method 文档字符串应当描述其功能、输入参数、返回值，如果有复杂算法和实现，也需要写清晰
· 不要写错误注释，不要无谓注释
· # bad 无谓注释
· x = x + 1 # increase x by 1
·
· # bad 错误注释
· x = x - 1 # increase x by 1
· 优先使用英文写注释，英文不好所有写中文，否则更加看不懂
异常
· 不要容易使用 try/except
· except 背面需要指定捕获异常，裸露 except 会捕获所有异常，意味着会隐藏潜在问题
· 可以有各种 except 语句，捕获各种异常，分别做异常解决
· 使用 finally 子句来解决某些收尾操作
· try/except 里内容不要太多，只在也许抛出异常地方使用，如：
· # bad
· try:
· user = User()
· user.name = "leon"
· user.age = int(age) # 也许抛出异常
· user.created_at = datetime.datetime.utcnow()
·
· db.session.add(user)
· mit() # 也许抛出异常
· except:
· db.session.rollback()
·
· # better
· try:
· age = int(age)
· except (TypeError，ValueError):
· return # 或别操作
·
· user = User()
· user.name = "leon"
· user.age = age
· user.created_at = datetime.datetime.utcnow()
· db.session.add(user)
·
· try:
· mit()
· except sqlalchemy.exc.SQLAlchemyError：# 或者更详细异常
· db.session.rollback()
· finally:
· db.session.close()
· 从 Exception 而不是 BaseException 继承自定义异常类
Class（类）
· 显示写明父类，如果不是继承自别类，就继承自 object 类
· 使用 super 调用父类办法
· 支持多继承，即同步有各种父类，建议使用 Mixin
编码建议
字符串
· 使用字符串 join 办法拼接字符串
· 使用字符串类型办法，而不是 string 模块办法
· 使用 startswith 和 endswith 办法比较前缀和后缀
· 使用 format 办法格式化字符串
比较
· 空 list, str, tuple, set, dict 和 0, 0.0, None 都是 False
· 使用 if some_list 而不是 if len(some_list) 判断某个 list 与否为空，其她类型同理
· 使用 is 和 is not 与单例（如 None）进行比较，而不是用 == 和 !=
· 使用 if a is not None 而不是 if not a is None
· 用 isinstance 而不是 type 判断类型
· 不要用 == 和 != 与 True 和 False 比较（除非有特殊状况，如在 sqlalchemy 中也许用到）
· 使用 in 操作：
1. 用 key in dict 而不是 dict.has_key()
2. # bad
3. if d.has_key(k):
4. do_something()
5.
6. # good
7. if k in d:
8. do_something()
9. 用 set 加速 “存在性” 检查，list 查找是线性，复杂度 O(n)，set 底层是 hash table，复杂度 O(1)，但用 set 需要比 list 更多内存空间
其她
· 使用列表表达式（list comprehension），字典表达式(dict comprehension，Python 2.7+) 和生成器(generator)
· dict  get 办法可以指定默认值，但有些时候应当用 [] 操作，使得可以抛出 KeyError
· 使用 for item in list 迭代 list, for index，item in enumerate(list) 迭代 list 并获取下标
· 使用内建函数 sorted 和 list.sort 进行排序
· 适量使用 map, reduce, filter 和 lambda，使用内建 all, any 解决各种条件判断
· 使用 defaultdict (Python 2.5+), Counter(Python 2.7+) 等 “冷门” 但好用原则库算法和数据构造
· 使用装饰器(decorator)
· 使用 with 语句解决上下文
· 有些时候不要对类型做太过严格限制，运用 Python 鸭子类型（Duck Type）特性
· 使用 logging 记录日记，配备好格式和级别
· 理解 Python Magic Method：A Guide to Python’s Magic Methods, Python 魔术办法指南
· 阅读先进开源代码，如 Flask 框架, Requests for Humans
· 不要重复造轮子，查看原则库、PyPi、Github、Google 等使用既有先进解决方案