请注意这一点:没有编码规范的代码没有阅读价值,也更谈不上复用。
目前业界比较流行的Python的编码规范目前主要有PEP8的编程、Google的编码风格、Python Guide和Pocoo StyleGuide等等,我认为无论是哪一种编码规范和风格,最重要的是要在团队中有一套统一或者近乎一致的编码规范和风格,这样才能确保协作效率和降低沟通成本。目前我所在的团队并没有一套规范,那么这个伟大的任务又要落在我手里来实现啦,哇哈哈:-D。
先说明一下,设计这套统一编码规范的原则只有一个:Simple is the best,简单实用是核心指导原则,编码规范要符合编码习惯和提升代码可读性。这套编码规范是基于PEP8规范的,但是同时参考Google的编码风格和大神编写的"Strunk & White"风格。
命名
文件名、包名、模块名:全小写,使用下划线可以改善可读性可以加入,如my_package。
类:总是使用首字母大写单词串。如MyClass。
函数、方法:函数名应该为小写,可以用下划线风增加可读性,如my_example_function。
变量:小写,尽量避免单字母变量,尽量让变量有意义。
常量:要求全部字幕大写,可以用下划线风增加可读性,如GLOBAL_VAR_NAME。
内部(Internal):使用(_)开头表示模块变量或函数是protected 的(使用import * from时不会包含);使用(__)开头表示实例变量或方法表示类内私有,类实例不能调用。
缩写:名中含有长单词,对某个单词进行缩写。这时应使用约定成俗的缩写方式。 例如:function 缩写为 fn;text 缩写为 txt ;object 缩写为 obj ;count 缩写为 cnt;number 缩写为 num 等。
布局
最重要的话写在第一句:如果懒得跟我一样的话,使用pycharm IDE用快捷键Ctrl+Alt+L就可以完成统一的代码布局。
在不使用这个IDE或者忘了用快捷键的情况下,请注意以下统一的代码布局:
代码长度:每行不超过80个字符。这一点pycharm没有这么严格,但是希望大家尽力做到,这样确保其他同事可以轻松愉快地阅读每一行代码。
空行:用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割。
缩进:使用4个空格作为一个缩进层次,尽量不要用8个空格。
分号:不要使用分号,尽管是用了也没有错。
括号:括号使用原则是越少越好,不要在返回语句或者条件语句中使用括号,例如:
空格(请尽量不要用制表符TAB,如果用了请保持一致):
括号内不使用空格;
不在逗号和冒号前使用空格,在其后面添加(跟英文写作一样);
二元操作符 【赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, notin, is, is not), 布尔(and, or, not)】两边都使用空格,
参数列表里不要带空格
以上截图来自《Google python style guide》
注释
python单行注释用#字符开头即可注释后面的内容,对于重要语句进行注释包括解释说明和提醒的作用。 python多行注释可以用’’’或者”””开头并以相同的用’’’或者”””结尾即可注释多行语句。
特别说明: python的方法内置对象doc String ,它可以用于模块、函数和类的描述,在写方法的时候,只要在方法声明下面进行多行注释。在引用或者使用的场景下,可以通过dir或者help方法可以查看该方法的使用帮助。python的方法注释可以参照下图,pycharm支持自动生成注释,比较方便。
Python 有一种独一无二的的注释方式: 使用文档字符串. 文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc 所用. (你可以在你的模块上运行pydoc 试一把, 看看它长什么样). 我们对文档字符串的惯例是使用三重双引号. 一个文档字符串应该这样组织: 首先是一行以句号, 问号或惊叹号结尾的概述. 接着是一个空行. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐。注意上图中的函数注释,文档字符串应该包含函数做什么, 以及输入和输出的详细描述. 通常, 不应该描述”怎么做”, 除非是一些复杂的算法. 对于技巧性的代码, 块注释或者行内注释是最重要的. 文档字符串应该提供足够的信息, 当别人编写代码调用该函数时, 他不需要看一行代码, 只要看文档字符串就可以了. 应该给参数单独写文档. 在冒号后跟上解释,
导入
可以使用两种导入的方法:
1.使用 import x 来导入包和模块。
2.使用 form x import y , 其中x 是包前缀, y 是不带前缀的模块名。
在后面讲述的common-lib库中,建议大家使用from common-lib import *这样的导入,在这个自定义库的__init__.py文件中已经定义了哪些可以导入哪些不需要导入。比较方便。
使用上述的导入方法的时候,要使用绝对路径而非相对路径,避免重复导入。
Main入口
要求所有新建的py文件都要有Main的入口,且必须总是检查该导如的主程序是否被执行。
Pycharm支持python代码模板,建议大家使用这个模板。
#-*- encoding:UTF-8 -*- from __future__ import division import sys __author__ = '$USER' def main(): pass if __name__ == '__main__': reload(sys) print "START: system-encoding[%s]"%sys.getdefaultencoding() main()
这个代码执行的时候先检查系统的编码,这个TIP是我踩过很多坑之后的教训,这样可以让你每次都知道当前程序运行的编码。
参考文档
《Google-Python-Style-Guide》
《Python开发编码规范(PEP8)》
《The Elements of Python Style》