2019-01-29 Python代码规范

程序模板

@FileName:  
 
@Author:xx@ic.net.cn  
 
@Create date:  
 
@description:用一行文字概述模块或脚本,用句号结尾。  
 
@Update date:  
 
@Vindicator: xx@ic.net.cn  
 
@File URL: http://idea.icgoo.net/xxxxxxx  
 
@svn Path: svn://svn.icinfo.net/xxxxxx  
  
"""  
  
#add by XXX  or  modify by XXX  
def Function(parameter1 ,parameter2...):  
''''' 
    @description: 
    @parameter1: 
    @parameter2: 
    @... 
    @return: 
'''

基本原则

方便代码的交流和维护不影响编码的效率,不与大众习惯冲突。使代码更美观,阅读更方便。使代码的逻辑更清晰,更易于理解。

编码

1.所有的 Python 脚本文件都应在文件头标上如下标识或其兼容格式的标识
2.设置编辑器,默认保存为 utf-8 格式
3.不论什么情况使用 UTF-8 吧!这是王道!-*- coding:utf-8 -*- 或 #coding=utf-8

命名

一致的命名可以给开发人员减少许多麻烦,而恰如其分的命名则可以大幅提高代码的可读性,降低维护成本。 Python库的命名约定有点混乱,所以我们将永远不能使之变得完全一致,不过还是有公认的命名规范的。 新的模块和包(包括第三方的框架)必须符合这些标准,但对已有的库存在不同风格的, 保持内部的一致性是首选的。一些特殊的字符要避免。如小写字母'l','o'

模块名

  1. 模块应该是不含下划线的,简短的,小写的名字。 例:module.py
  2. 对于包内使用的模块,可以加一个下划线前缀。 例:_internal_module.py

类名

几乎没有例外,类名总是使用首字母大写单词串(CapWords)的约定。不使用下划线连接单词,也不加入 C、T 等前缀。 例:

class ThisIsAClass(object):

     pass

函数名

函数名全部小写,由下划线连接各个单词,类似mixedCase函数名仅被允许用于这种风格已经占优势的上下文(如: threading.py) 以便保持向后兼容。 例:

def this_is_a_func(self):

     pass

变量名

  1. 变量名全部小写,由下划线连接各个单词
  2. 不论是类成员变量还是全局变量,均不使用 m 或 g 前缀
  3. 私有类成员使用单一下划线前缀标识,多定义公开成员,少定义私有成员。
  4. 变量名不应带有类型信息,因为 Python 是动态类型语言。如 iValue、names_list、dict_obj 等都是不好的命名。
    例:
  color = WHITE  

  this_is_a_variable = 1

常量名

常量名所有字母大写,由下划线连接各个单词,例如:

  WHITE = 0xffffffff  

  THIS_IS_A_CONSTANT = 1 

异常名

如果模块对所有情况定义了单个异常,它通常被叫做errorError 似乎内建(扩展)的模块使用"error"(例如:os.error), 而Python模块通常用Error(例如:xdrlib.Error)。 趋势是使用(CapWords)

缩写

  1. 命名应当尽量使用全拼写的单词
  2. 常用的缩写,如 XML、ID等,在命名时也应只大写首字母。例:class XmlParser(object):pass
  3. 命名中含有长单词,对某个单词进行缩写。例:function 缩写为 fn;text 缩写为 txt;object 缩写为 obj

特殊命名

  1. 用下划线作前导或结尾的特殊形式是被公认的_single_leading_underscore(以一个下划线作前导): 弱的"内部使用(internal use)"标志。 例: from M import会导入以下划线开头的对象。
  2. single_trailing_underscore_(以一个下划线结尾):用于避免与Python关键词的冲突例:Tkinter.Toplevel(master, class_='ClassName')
  3. __double_leading_underscore(双下划线): 从Python 1.4起为类私有名
  4. __double_leading_and_trailing_underscore__ 特殊的(magic) 对象或属性,存在于用户控制的(user-controlled)名字空间。例:__init____import____file__

缩进

  1. 使用制表符还是空格?
  • 永远不要混用制表符和空格.建议使用空格。
  • 我们内部应该都是使用的4个空格的tab。

空行

适当的空行有利于增加代码的可读性,加空行可以参考如下几个准则
1.在类、函数的定义间加空行

  • 用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割。
  1. 额外的空行可被用于分割一组相关函数
  2. 在 import 不同种类的模块间加空行
  3. 在函数中的逻辑段落间加空行,即把相关的代码紧凑写在一起,作为一个逻辑段落,段落间以空行分隔

空格

空格在 Python 代码中是有意义的,因为 Python 的语法依赖于缩进,在行首的空格称为前导空格。这里不谈这个。 非前导空格在 Python 代码中没有意义,但适当地加入非前导空格可以增进代码的可读性。例如:

在二元算术、逻辑运算符前后加空格:
a = b + c(好) a=b+c(不好)

“:”用在行尾时前后皆不加空格,如分枝、循环、函数和类定义语言;用在非行尾时两端加空格,如 dict 对象的定义
d = {'key' : 'value'}(好) d = {'key':'value'}(不好)

括号(含圆括号、方括号和花括号)前后不加空格
do_something(arg1, arg2)(好) do_something( arg1, arg2 )(不好)

逗号后面加一个空格,前面不加空格
print x, y(好) print x , y(不好)

函数调用,索引切片,字典取值不要用空格
spam(x)(好) spam (x)(不好); listi list [i](不好); dict[key](好) dict [key](不好)

断行

尽管现在的宽屏显示器已经可以单屏显示超过 256 列字符,但本规范仍然坚持行的最大长度不得超过 78 个字符的标准

  1. 为长变量名换一个短名
    例: this._is.a.very.long.variable_name = this._is.another.long.variable_name (不好)
    variable_name = this._is.another.long.variable_name (好)
  1. 在括号(包括圆括号、方括号和花括号)内换行。例:
     class Edit(Widget):
          def __init__(self, parent, width,
              font = FONT, color = BLACK, pos = POS, style = 0): # 注意:多一层缩进
              pass

如果行长到连第一个括号内的参数都放不下,则每个元素都单独占一行。例:

      very_very_very_long_variable_name = ui.widgets.Edit(
          panrent,
          width,
          font,
          color,
          pos) # 注意:多一层缩进
      do_sth_with(very_very_very_long_variable_name)
  1. 在长行加入续行符强行断行,断行的位置应在操作符前,且换行后多一个缩进,以使维护人员看代码的时候看到代码行首即可判定这里存在换行。 例:
      if color == WHITE or color == BLACK \
              or color == BLUE: # 注意 or 操作符在新行的行首而不是旧行的行尾,上一行的续行符不可省略
          do_something(color);
      else:
          do_something(DEFAULT_COLOR);

导入

Imports 通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前。Imports应该有顺序地成组安放。对于内部包的导入是不推荐使用相对导入的.对所有导入都要使用包的绝对路径。import应该按照从最常用到最不常用的顺序分组放置,这几种模块中用空行分隔开来。

import标准库
import第三方库
importGoogle App Engine 相关库
importDjango 框架相关库
importSoC framework 相关库
import基于 SoC 框架的模块
import应用程序特有的内容

注释

业界普遍认同 Python 的注释分为两种的概念,一种是由 # 开头的“真正的”注释,另一种是 docstrings。前者表明为何选择当前实现以及这种实现的原理和难点,后者表明如何使用这个包、模块、类、函数(方法),甚至包括使用示例和单元测试。坚持适当注释原则。对不存在技术难点的代码坚持不注释,对存在技术难点的代码必须注释 推荐对每一个包、模块、类、函数(方法)写 docstrings,除非代码一目了然,非常简单 包、模块、类、函数的第一个语句如果是字符串那么就是一个__ doc__ String。

文件注释

每个文件开头都应该包含一个带有版权信息和许可声明的块注释。

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 217,907评论 6 506
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 92,987评论 3 395
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 164,298评论 0 354
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 58,586评论 1 293
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 67,633评论 6 392
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 51,488评论 1 302
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 40,275评论 3 418
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 39,176评论 0 276
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 45,619评论 1 314
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,819评论 3 336
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,932评论 1 348
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 35,655评论 5 346
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 41,265评论 3 329
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,871评论 0 22
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,994评论 1 269
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 48,095评论 3 370
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 44,884评论 2 354

推荐阅读更多精彩内容

  • 最近写python对于一些代码规范问题感觉有些地方自己还需要加强,翻阅很多文章,特此奉上官方中文翻译版以便日后查看...
    PeterPZ阅读 3,489评论 0 15
  • 介绍 愚蠢的使用一致性是无知的怪物(A Foolish Consistency is the Hobgoblin ...
    slords阅读 1,976评论 0 2
  • 包(lib)、模块(module) 在Python中,存在包和模块两个常见概念。 模块:编写Python代码的py...
    清清子衿木子水心阅读 3,805评论 0 27
  • 一、Python简介和环境搭建以及pip的安装 4课时实验课主要内容 【Python简介】: Python 是一个...
    _小老虎_阅读 5,746评论 0 10
  • 今天周五!晚上,我们家的家庭会议日!自从看正面管教的书之后,和娃爸商量这天晚上只要有空我们一家人就坐一起聊聊天,虽...
    Wendyywh阅读 155评论 0 0