Python编码规范.docx

1、Python编码规范Python编码规范目录(TABLE OF CONTENTS)1.介绍这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python代码，请查阅相关的关于在Python的C实现中C代码风格指南的描述。2.版权声明这篇文档改编自Guido最初的Python风格指南一文，并从Barrys style guide中添加了部分内容。在有冲突的地方，Guide的风格规则应该是符合本PEP的意图。这篇PEP仍然尚未完成(实际上，它可能永远都不会完成)。3.一致性建议在这篇风格指导中的一致性是重要的。在一个项目内的一致性更重要。在一个模块或函数内的一致性最重要。但最

2、重要的是:知道何时会不一致有时只是没有实施风格指导。当出现疑惑时，运用你的最佳判断，看看别的例子，然后决定怎样看起来更好。并且要不耻下问！打破一条既定规则的两个好理由:一、 当应用这个规则是将导致代码可读性下降，即便对某人来说，他已经习惯于按这条规则来阅读代码了。二、为了和周围的代码保持一致而打破规则(也许是历史原因)，虽然这也是个清除其它混乱的好机会(真正的XP风格)。4.代码的布局4.1.缩进4个空格一个缩进层次。对于确实古老的代码，你不希望产生混乱，可以继续使用8空格的制表符(8-space tabs)。Emacs Python-mode自动发现文件中主要的缩进层次，依此设定缩进参数。4

3、.2.制表符还是空格Python 依赖缩进来确定代码块的层次，行首空白符主要有两种：tab 和空格，但严禁两者混用。如果使用 tab 缩进，设定 tab 为 4 个空格。公司内部推荐使用 4 个空格的 tab 进行缩进。4.3.行的最大长度周围仍然有许多设备被限制在每行80字符；而且，窗口限制在80个字符。使将多个窗口并排放置成为可能。在这些设备上使用默认的折叠方式看起来有点丑陋。因此，请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符)，对顺序排放的大块文本(文档字符串或注释)，推荐将长度限制在72字符。折叠长行的首选方法是使用Pyhon支持的圆括号，方括号和花括号内的行延续

4、。如果需要，你可以在表达式周围增加一对额外的圆括号，但是有时使用反斜杠看起来更好，确认恰当得缩进了延续的行。一些例子:图14.4.空行适当的空行有利于增加代码的可读性，加空行可以参考如下几个准则：一、在类、函数的定义间加空行；二、在 import 不同种类的模块间加空行；三、在函数中的逻辑段落间加空行，即把相关的代码紧凑写在一起，作为一个逻辑段落，段落间以空行分隔；4.5.编码Python脚本可以通过在文件头上加“#-*- coding: xxx -*-”来设置编辑器默认保存的编码格式。例如：#-*- coding: utf-8 -*-。5.导入通常应该在单独的行中导入(Imports)，例如

5、:图2但是这样也是可以的:图3Imports 通常被放置在文件的顶部，仅在模块注释和文档字符串之后，在模块的全局变量和常量之前。Imports应该有顺序地成组安放:一、标准库的导入(Imports )，即Python内置模块。二、相关的主包(major package)的导入，即第三方模块。三、特定应用的导入(imports)，即自己开发的模块。你应该在每组导入之间放置一个空行，对于内部包的导入是不推荐使用相对导入的，对所有导入都要使用包的绝对路径。从一个包含类的模块中导入类时，通常可以写成这样:图4如果这样写导致了本地名字冲突，那么就这样写:图5即使用MyClass.MyClass和foo.

6、bar.YourClass.YourClass。6.表达式和语句中的空格紧挨着圆括号，方括号和花括号的，如:图6紧贴在逗号，分号或冒号前的，如:图7紧贴着函数调用的参数列表前开式括号(open parenthesis )的，如:图8紧贴在索引或切片，开始的开式括号前的，如:图9在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格，如:图106.1.其它建议始终在这些二元运算符两边放置一个空格:赋值(=)， 比较(=，!=，=，=，in，not in，is，is not)，布尔运算 (and，or，not)。按你的看法在算术运算符周围插入空格。 始终保持二元运算符两边空格的一致一些例子:图

7、11不要在用于指定关键字参数或默认参数值的=号周围使用空格，例如:图12不要将多条语句写在同一行上:图137.注释同代码不一致的注释比没注释更差。当代码修改时，始终优先更新注释!注释应该是完整的句子，如果注释是一个短语或句子，首字母应该大写，除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写)。如果注释很短，最好省略末尾的句号。注释块通常由一个或多个由完整句子构成的段落组成，每个句子应该以句号结尾。你应该在句末，句号后使用两个空格，以便使Emacs的断行和填充工作协调一致。用英语书写时，断词和空格是可用的。非英语国家的Python程序员:请用英语书写你的注释，除非你120%的确信这

8、些代码不会被不懂你的语言的人阅读。7.1.注释块注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次。注释块中每行以#和一个空格开始(除非他是注释内的缩进文本)。注释块内的段落以仅含单个#的行分割。注释块上下方最好有一空行包围(或上方两行下方一行，对一个新函数定义段的注释)。7.2.行内注释一个行内注释是和语句在同一行的注释，行内注释应该谨慎适用，行内注释应该至少用两个空格和语句分开，它们应该以#和单个空格开始:图14如果语意是很明了的，那么行内注释是不必要的，事实上是应该被移除的。不要这样写:图15但是有时，这样是有益的:图168.文档化为所有公共模块，函数，类和方法编写

9、文档字符串。文档字符串对非公开的方法不是必要的，但你应该有一个描述这个方法做什么的注释。这个注释应该在def这行后。PEP 257 描述了好的文档字符串的约定。一定注意，多行文档字符串结尾的应该单独成行，例如:图179.版本注记如果你要将RCS或CVS的杂项(crud)包含在你的源文件中，按如下做:图18这个行应该包含在模块的文档字符串之后，所有代码之前，上下用一个空行分割。10.命名约定Python库的命名约定有点混乱，所以我们将永远不能使之变得完全一致，不过还是有公认的命名规范的。新的模块和包(包括第三方的框架)必须符合这些标准，但对已有的库存在不同风格的，保持内部的一致性是首选的。10.

10、1.描述:命名风格有许多不同的命名风格。以下的有助于辨认正在使用的命名风格，独立于它们的作用。以下的命名风格是众所周知的:- b (单个小写字母)- B (单个大写字母)- Lowercase（小写）- lower_case_with_underscores（有下划线的小写）- UPPERCASE（大写）- UPPER_CASE_WITH_UNDERSCORES（有下划线的大写）- CapitalizedWords (或 CapWords，CamelCase这样命名是因为可从字母的大小写分出单词。这有时也被当作StudlyCaps。- mixedCase (与CapitalizedWords的

11、不同在于首字母小写!)- Capitalized_Words_With_Underscores（有下划线的首字母大写）还有用短的特别前缀将相关的名字聚合在一起的风格。这在Python中不常用，但是出于完整性要提一下，例如，os.stat()函数返回一个元组，他的元素传统上说名如st_mode， st_size，st_mtime等等。X11库的所有公开函数以X开头。(在Python中，这个风格通常认为是不必要的，因为属性和方法名以对象作前缀，而函数名以模块名作前缀。)另外，以下用下划线作前导或结尾的特殊形式是被公认的(这些通常可以和任何习惯组合):- _single_leading_unders

12、core(单个下划线作前导):弱的“内部使用(internal use)”标志，例如，“from M import *”不会导入以下划线开头的对象。- single_trailing_underscore_(单个下划线结尾): 用于避免与Python关键词的冲突，例如:“Tkinter.Toplevel(master，class_=ClassName)”。- _double_leading_underscore(双下划线):从Python 1.4起为类私有名。- _double_leading_and_trailing_underscore_:“magic”对象或属性，存在于用户控制的(use

13、r-controlled)名字空间，例如:_init_， _import_ 或_file_。有时它们被用户定义用于触发某个魔法行为(例如:运算符重载):有时被构造器插入，以便自己使用或为了调试。因此，在未来的版本中，构造器(松散得定义为Python解释器和标准库)可能打算建立自己的魔法属性列表，用户代码通常应该限制将这种约定作为己用。欲成为构造器的一部分的用户代码可以在下滑线中结合使用短前缀，例如:_bobo_magic_attr_。10.2.说明:命名约定一致的命名可以给开发人员减少许多麻烦，而恰如其分的命名则可以大幅提高代码的可读性，降低维护成本。10.2.1.常量名常量名所有字母大写，由

14、下划线连接各个单词，例如：图1910.2.2.变量名变量名全部小写，由下划线连接各个单词，例如：图20不论是类成员变量还是全局变量，均不使用 m 或 g 前缀。私有类成员使用单一下划线前缀标识，多定义公开成员，少定义私有成员。变量名不应带有类型信息，因为 Python 是动态类型语言。如 iValue、names_list、dict_obj 等都是不好的命名。10.2.3.函数名函数名的命名规则与变量名相同。例如：图2110.2.4.类名类名单词首字母大写，不使用下划线连接单词，也不加入 C、T 等前缀。例如：图2210.2.5.模块名模块名全部小写，对于包内使用的模块，可以加一个下划线前缀，

15、例如：图2310.2.6.包名包的命名规范与模块相同。10.2.7.缩写命名应当尽量使用全拼写的单词，缩写的情况有如下两种：常用的缩写，如 XML、ID等，在命名时也应只大写首字母，例如：图24命名中含有长单词，对某个单词进行缩写。这时应使用约定成俗的缩写方式，如去除元音、包含辅音的首字符等方式，例如：图2510.2.8.特定的命名方式主要是指 _xxx_ 形式的系统保留字命名法。项目中也可以使用这种命名，它的意义在于这种形式的变量是只读的，这种形式的类成员函数尽量不要重载。例如：图26其中 _id_、_parent_ 和 _message_ 都采用了系统保留字命名法。11.设计建议单个元素(

16、singletons)的比较，如None 应该永远用:is或is not来做。当你本意是“if x is not None”时，对写成“if x”要小心。例如当你测试一个默认为None的变量或参数是否被设置为其它值时，这个值也许在布尔上下文(Boolean context)中是false！基于类的异常总是好过基于字符串的异常。模块和包应该定义它们自己的域内特定的基异常类，基类应该是内建的Exception类子类。还始终包含一个类的文档字符串。例如:图27使用字符串方法(methods)代替字符串模块，除非必须向后兼容Python 2.0以前的版本。字符串方法总是非常快，而且和unicode字符

17、串共用同样的API(应用程序接口)在检查前缀或后缀时避免对字符串进行切片。用startswith()和endswith()代替，因为它们是明确的并且错误更少。例如:图28例外是如果你的代码必须工作在Python 1.5.2 (但是我们希望它不会发生！)，对象类型的比较应该始终用isinstance()代替直接比较类型，例如:图29检查一个对象是否是字符串时，紧记它也可能是unicode字符串！在Python 2.3，str和unicode有公共的基类，basestring，所以你可以这样做:图30在Python 2.2类型模块为此定义了StringTypes类型，例如:图31在Python 2

18、.0和2.1，你应该这样做:图32对序列，(字符串，列表，元组)，使用空列表是false这个事实，因此“if not seq”或“if seq”比“if len(seq)”或“if not len(seq)”好。书写字符串文字时不要依赖于有意义的后置空格。这种后置空格在视觉上是不可辨别的，并且有些编辑器(特别是近来，reindent.py)会将它们修整掉。不要用=来比较布尔型的值以确定是True或False(布尔型是Pythn 2.3中新增的):图33对于条件和循环语句，不要写成一行，否则不是好的代码，例如：图3412.已有代码对于项目中已有的代码，可能因为历史遗留原因不符合本规范，应当看作可以容忍的特例，允许存在；但不应在新的代码中延续旧的风格。对于第三方模块，可能不符合本规范，也应看作可以容忍的特例，允许存在；但不应在新的代码中使用第三方模块的风格。tab 与空格混用的缩进是不可容忍的，在运行项目时应使用 t 或 tt 选项排查这种可能性存在。出现混用的情况时，如果是公司开发的基础类库代码，应当通知类库维护人员修改；第三方模块则可以通过提交 patch 等方式敦促开发者修正问题。13.已有风格开发人员往往在加入项目之前已经形成自有的编码风格，加入项目后应以本规范为准编写代码。特别是匈牙利命名法，因为带有类型信息，并不适合 Python 编程，不应在 Python 项目中应用。