Python编码规范.docx
《Python编码规范.docx》由会员分享,可在线阅读,更多相关《Python编码规范.docx(15页珍藏版)》请在冰豆网上搜索。
Python编码规范
Python编码规范
目录(TABLEOFCONTENTS)
1.介绍
这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python代码,请查阅相关的关于在Python的C实现中C代码风格指南的描述。
2.版权声明
这篇文档改编自Guido最初的《Python风格指南》一文,并从《Barry'sstyleguide》中添加了部分内容。
在有冲突的地方,Guide的风格规则应该是符合本PEP的意图。
这篇PEP仍然尚未完成(实际上,它可能永远都不会完成)。
3.一致性建议
在这篇风格指导中的一致性是重要的。
在一个项目内的一致性更重要。
在一个模块或函数内的一致性最重要。
但最重要的是:
知道何时会不一致——有时只是没有实施风格指导。
当出现疑惑时,运用你的最佳判断,看看别的例子,然后决定怎样看起来更好。
并且要不耻下问!
打破一条既定规则的两个好理由:
一、当应用这个规则是将导致代码可读性下降,即便对某人来说,他已经习惯于按这条规则来阅读代码了。
二、为了和周围的代码保持一致而打破规则(也许是历史原因),虽然这也是个清除其它混乱的好机会(真正的XP风格)。
4.代码的布局
4.1.缩进
4个空格一个缩进层次。
对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-spacetabs)。
EmacsPython-mode自动发现文件中主要的缩进层次,依此设定缩进参数。
4.2.制表符还是空格
Python依赖缩进来确定代码块的层次,行首空白符主要有两种:
tab和空格,但严禁两者混用。
如果使用tab缩进,设定tab为4个空格。
公司内部推荐使用4个空格的tab进行缩进。
4.3.行的最大长度
周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符。
使将多个窗口并排放置成为可能。
在这些设备上使用默认的折叠方式看起来有点丑陋。
因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符),对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符。
折叠长行的首选方法是使用Pyhon支持的圆括号,方括号和花括号内的行延续。
如果需要,你可以在表达式周围增加一对额外的圆括号,但是有时使用反斜杠看起来更好,确认恰当得缩进了延续的行。
一些例子:
图1
4.4.空行
适当的空行有利于增加代码的可读性,加空行可以参考如下几个准则:
一、在类、函数的定义间加空行;
二、在import不同种类的模块间加空行;
三、在函数中的逻辑段落间加空行,即把相关的代码紧凑写在一起,作为一个逻辑段落,段落间以空行分隔;
4.5.编码
Python脚本可以通过在文件头上加“#-*-coding:
xxx-*-”来设置编辑器默认保存的编码格式。
例如:
#-*-coding:
utf-8-*-。
5.导入
通常应该在单独的行中导入(Imports),例如:
图2
但是这样也是可以的:
图3
Imports通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前。
Imports应该有顺序地成组安放:
一、标准库的导入(Imports),即Python内置模块。
二、相关的主包(majorpackage)的导入,即第三方模块。
三、特定应用的导入(imports),即自己开发的模块。
你应该在每组导入之间放置一个空行,对于内部包的导入是不推荐使用相对导入的,对所有导入都要使用包的绝对路径。
从一个包含类的模块中导入类时,通常可以写成这样:
图4
如果这样写导致了本地名字冲突,那么就这样写:
图5
即使用"MyClass.MyClass"和"foo.bar.YourClass.YourClass"。
6.表达式和语句中的空格
紧挨着圆括号,方括号和花括号的,如:
图6
紧贴在逗号,分号或冒号前的,如:
图7
紧贴着函数调用的参数列表前开式括号(openparenthesis)的,如:
图8
紧贴在索引或切片,开始的开式括号前的,如:
图9
在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格,如:
图10
6.1.其它建议
始终在这些二元运算符两边放置一个空格:
赋值(=),比较(==,<,>,!
=,<>,<=,=,in,notin,is,isnot),布尔运算(and,or,not)。
按你的看法在算术运算符周围插入空格。
始终保持二元运算符两边空格的一致一些例子:
图11
不要在用于指定关键字参数或默认参数值的'='号周围使用空格,例如:
图12
不要将多条语句写在同一行上:
图13
7.注释
同代码不一致的注释比没注释更差。
当代码修改时,始终优先更新注释!
注释应该是完整的句子,如果注释是一个短语或句子,首字母应该大写,除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写)。
如果注释很短,最好省略末尾的句号。
注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾。
你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致。
用英语书写时,断词和空格是可用的。
非英语国家的Python程序员:
请用英语书写你的注释,除非你120%的确信这些代码不会被不懂你的语言的人阅读。
7.1.注释块
注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次。
注释块中每行以‘#’和一个空格开始(除非他是注释内的缩进文本)。
注释块内的段落以仅含单个‘#’的行分割。
注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释)。
7.2.行内注释
一个行内注释是和语句在同一行的注释,行内注释应该谨慎适用,行内注释应该至少用两个空格和语句分开,它们应该以'#'和单个空格开始:
图14
如果语意是很明了的,那么行内注释是不必要的,事实上是应该被移除的。
不要这样写:
图15
但是有时,这样是有益的:
图16
8.文档化
为所有公共模块,函数,类和方法编写文档字符串。
文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释。
这个注释应该在"def"这行后。
PEP257描述了好的文档字符串的约定。
一定注意,多行文档字符串结尾的"""应该单独成行,例如:
图17
9.版本注记
如果你要将RCS或CVS的杂项(crud)包含在你的源文件中,按如下做:
图18
这个行应该包含在模块的文档字符串之后,所有代码之前,上下用一个空行分割。
10.命名约定
Python库的命名约定有点混乱,所以我们将永远不能使之变得完全一致,不过还是有公认的命名规范的。
新的模块和包(包括第三方的框架)必须符合这些标准,但对已有的库存在不同风格的,保持内部的一致性是首选的。
10.1.描述:
命名风格
有许多不同的命名风格。
以下的有助于辨认正在使用的命名风格,独立于它们的作用。
以下的命名风格是众所周知的:
-b(单个小写字母)
-B(单个大写字母)
-Lowercase(小写)
-lower_case_with_underscores(有下划线的小写)
-UPPERCASE(大写)
-UPPER_CASE_WITH_UNDERSCORES(有下划线的大写)
-CapitalizedWords(或CapWords,CamelCase这样命名是因为可从字母的大小写分出单词。
这有时也被当作StudlyCaps。
-mixedCase(与CapitalizedWords的不同在于首字母小写!
)
-Capitalized_Words_With_Underscores(有下划线的首字母大写)
还有用短的特别前缀将相关的名字聚合在一起的风格。
这在Python中不常用,但是出于完整性要提一下,例如,os.stat()函数返回一个元组,他的元素传统上说名如st_mode,st_size,st_mtime等等。
X11库的所有公开函数以X开头。
(在Python中,这个风格通常认为是不必要的,因为属性和方法名以对象作前缀,而函数名以模块名作前缀。
)
另外,以下用下划线作前导或结尾的特殊形式是被公认的(这些通常可以和任何习惯组合):
-_single_leading_underscore(单个下划线作前导):
弱的“内部使用(internaluse)”标志,例如,“fromMimport*”不会导入以下划线开头的对象。
-single_trailing_underscore_(单个下划线结尾):
用于避免与Python关键词的冲突,例如:
“Tkinter.Toplevel(master,class_='ClassName')”。
-_double_leading_underscore(双下划线):
从Python1.4起为类私有名。
-_double_leading_and_trailing_underscore_:
“magic”对象或属性,存在于用户控制的(user-controlled)名字空间,例如:
_init_,_import_或_file_。
有时它们被用户定义用于触发某个魔法行为(例如:
运算符重载):
有时被构造器插入,以便自己使用或为了调试。
因此,在未来的版本中,构造器(松散得定义为Python解释器和标准库)可能打算建立自己的魔法属性列表,用户代码通常应该限制将这种约定作为己用。
欲成为构造器的一部分的用户代码可以在下滑线中结合使用短前缀,例如:
_bobo_magic_attr__。
10.2.说明:
命名约定
一致的命名可以给开发人员减少许多麻烦,而恰如其分的命名则可以大幅提高代码的可读性,降低维护成本。
10.2.1.常量名
常量名所有字母大写,由下划线连接各个单词,例如:
图19
10.2.2.变量名
变量名全部小写,由下划线连接各个单词,例如:
图20
不论是类成员变量还是全局变量,均不使用m或g前缀。
私有类成员使用单一下划线前缀标识,多定义公开成员,少定义私有成员。
变量名不应带有类型信息,因为Python是动态类型语言。
如iValue、names_list、dict_obj等都是不好的命名。
10.2.3.函数名
函数名的命名规则与变量名相同。
例如:
图21
10.2.4.类名
类名单词首字母大写,不使用下划线连接单词,也不加入C、T等前缀。
例如:
图22
10.2.5.模块名
模块名全部小写,对于包内使用的模块,可以加一个下划线前缀,例如:
图23
10.2.6.包名
包的命名规范与模块相同。
10.2.7.缩写
命名应当尽量使用全拼写的单词,缩写的情况有如下两种:
常用的缩写,如XML、ID等,在命名时也应只大写首字母,例如:
图24
命名中含有长单词,对某个单词进行缩写。
这时应使用约定成俗的缩写方式,如去除元音、包含辅音的首字符等方式,例如:
图25
10.2.8.特定的命名方式
主要是指__xxx__形式的系统保留字命名法。
项目中也可以使用这种命名,它的意义在于这种形式的变量是只读的,这种形式的类成员函数尽量不要重载。
例如:
图26
其中__id__、__parent__和__message__都采用了系统保留字命名法。
11.设计建议
单个元素(singletons)的比较,如None应该永远用:
‘is’或‘isnot’来做。
当你本意是“ifxisnotNone”时,对写成“ifx”要小心。
例如当你测试一个默认为None的变量或参数是否被设置为其它值时,这个值也许在布尔上下文(Booleancontext)中是false!
基于类的异常总是好过基于字符串的异常。
模块和包应该定义它们自己的域内特定的基异常类,基类应该是内建的Exception类子类。
还始终包含一个类的文档字符串。
例如:
图27
使用字符串方法(methods)代替字符串模块,除非必须向后兼容Python2.0以前的版本。
字符串方法总是非常快,而且和unicode字符串共用同样的API(应用程序接口)在检查前缀或后缀时避免对字符串进行切片。
用startswith()和endswith()代替,因为它们是明确的并且错误更少。
例如:
图28
例外是如果你的代码必须工作在Python1.5.2(但是我们希望它不会发生!
),对象类型的比较应该始终用isinstance()代替直接比较类型,例如:
图29
检查一个对象是否是字符串时,紧记它也可能是unicode字符串!
在Python2.3,str和unicode有公共的基类,basestring,所以你可以这样做:
图30
在Python2.2类型模块为此定义了StringTypes类型,例如:
图31
在Python2.0和2.1,你应该这样做:
图32
对序列,(字符串,列表,元组),使用空列表是false这个事实,因此“ifnotseq”或“ifseq”比“iflen(seq)”或“ifnotlen(seq)”好。
书写字符串文字时不要依赖于有意义的后置空格。
这种后置空格在视觉上是不可辨别的,并且有些编辑器(特别是近来,reindent.py)会将它们修整掉。
不要用==来比较布尔型的值以确定是True或False(布尔型是Pythn2.3中新增的):
图33
对于条件和循环语句,不要写成一行,否则不是好的代码,例如:
图34
12.已有代码
对于项目中已有的代码,可能因为历史遗留原因不符合本规范,应当看作可以容忍的特例,允许存在;但不应在新的代码中延续旧的风格。
对于第三方模块,可能不符合本规范,也应看作可以容忍的特例,允许存在;但不应在新的代码中使用第三方模块的风格。
tab与空格混用的缩进是不可容忍的,在运行项目时应使用–t或–tt选项排查这种可能性存在。
出现混用的情况时,如果是公司开发的基础类库代码,应当通知类库维护人员修改;第三方模块则可以通过提交patch等方式敦促开发者修正问题。
13.已有风格
开发人员往往在加入项目之前已经形成自有的编码风格,加入项目后应以本规范为准编写代码。
特别是匈牙利命名法,因为带有类型信息,并不适合Python编程,不应在Python项目中应用。