Python 代码风格指南.docx

资源描述

Python 代码风格指南.docx

《Python 代码风格指南.docx》由会员分享，可在线阅读，更多相关《Python 代码风格指南.docx（27页珍藏版）》请在冰豆网上搜索。

Python 代码风格指南.docx

Python代码风格指南

介绍

本文档所提供的编码规范，适用于主要的Python发行版中组成标准库的Python代码。

请参阅PEP关于Python的C实现的C编码风格指南的描述。

本文档和PEP257（文档字符串规范）改编自Guido的《PythonStyleGuide》一文，并从《Barry'sstyleguide》添加了部分内容作为补充。

这篇风格指南随着时间的推移而逐渐演变，随着语言本身的变化，一些过去的约定已经过时，并确定了更多新的约定。

许多项目都有自己的编码风格指南。

如果有任何冲突，优先使用该项目特定的指南。

愚蠢地坚持一致性是无知的妖怪

Guido的一个重要的见解是，代码阅读的次数比编写的次数多。

这里提供的指南旨在提高代码的可读性，并使各种不同的Python代码一致。

如PEP20所说，“易读性非常重要”。

风格指南是关于一致性的。

与本风格指南一致很重要。

项目中的一致性更重要。

一个模块或功能中的一致性最重要。

最重要的是：

知道何时会不一致——有时风格指南就不适用了。

怀疑时，作出你最佳的判断。

看看其他的例子，并决定什么是最好的。

不要犹豫，尽管发问！

特别地：

不要只为遵从这个PEP而打破向后兼容性！

可以忽略部分风格指南的好理由，不要只为遵从这个PEP而打破向后兼容性！

忽视既定指南的一些其他的好理由：

1当应用指南会降低代码的可读性，即使对于那些习惯遵照这个PEP来阅读代码的人来说。

2与周围的代码保持一致也会破坏它（可能是历史原因）——虽然这也是收拾别人烂摊子的好机会（在真正的XP风格中）。

3因为问题代码先于指南，又没有其它的修改理由。

4代码需要兼容老版本，本风格指南不建议使用的Python特性。

代码布局

缩进

每级缩进用4个空格

连续行的折叠元素应该对齐

#与起始定界符对齐：

foo=long_function_name（var_one,var_two,

var_three,var_four）

#使用更多的缩进，以区别于其他代码

deflong_function_name（

var_one,var_two,var_three,

var_four）:

print（var_one）

#悬挂时，应该增加一级缩进

foo=long_function_name（

var_one,var_two,

var_three,var_four）

#悬挂不一定要4个空格

foo=long_function_name（

var_one,var_two,

var_three,var_four）

if语句条件块太长需要写成多行.

值得注意的是两个字符组成的关键字（例如if），加上一个空格，加上开括号，为后面的多行条件创建了一个4个空格的缩进。

这会给嵌入if内的缩进语句产生视觉冲突，因为它们也被缩进4个空格。

这个PEP没有明确如何（是否）进一步区分条件行和if语句内的行。

这种情况下，可以接受的选项包括，但不仅限于：

#不增加额外的缩进

if（this_is_one_thingand

that_is_another_thing）:

do_something（）

#添加一行注释，这将为支持语法高亮的编辑器提供一些区分

if（this_is_one_thingand

that_is_another_thing）:

#当两个条件都是真，我们将要执行

do_something（）

#在换行的条件语句前，增加额外的缩进

if（this_is_one_thing

andthat_is_another_thing）:

do_something（）

多行结构中的结束花括号/中括号/圆括号应该是最后一行的第一个非空白字符

my_list=[

1,2,3,

4,5,6,

]

result=some_function_that_takes_arguments（

'a','b','c',

'd','e','f',

）

或者是最后一行的第一个字符

my_list=[

1,2,3,

4,5,6,

]

result=some_function_that_takes_arguments（

'a','b','c',

'd','e','f',

）

制表符还是空格

空格是最优先的缩进方式

当已经使用制表符是，应该保持一致性，继续使用制表符

Python3不允许混合使用制表符和空格来缩进。

Python2的代码中混合使用制表符和空格的缩进，应该转化为完全使用空格。

调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告（warnings）。

使用-tt时警告（warnings）将变成错误（errors）.这些选项是被高度推荐的.

最大行长度

限制所有行最多79个字符。

下垂的长块结构限制为更少的文本（文档字符串或注释），行的长度应该限制在72个字符。

限制编辑器窗口宽度使得并排打开多个文件成为可能，并且使用代码审查工具显示相邻列的两个版本工作正常。

绝大多数工具的默认折叠会破坏代码的可视化结构，使其更难以理解。

编辑器中的窗口宽度设置为80个字符。

即使该工具将在最后一列中标记字形。

一些基于网络的工具可能不会提供动态的自动换行。

有些团队强烈喜欢较长的行长度。

对于代码维护完全或主要由一个团队的，可以在这个问题上达成协议，象征性的将行长度从80个字符增加到100个字符（有效地增加最大长度到99个字符）也是可以的，提供注释和文档字符串仍是72个字符。

Python标准库采取保守做法，要求行限制到79个字符（文档字符串/注释到72个字符）。

折叠长行的首选方法是使用Pyhon支持的圆括号,方括号（brackets）和花括号（braces）内的行延续。

长行可以在表达式外面使用小括号来变成多行。

连续行使用反斜杠更好。

反斜杠有时可能仍然是合适的。

例如，长的多行的with语句不能用隐式续行，可以用反斜杠：

#反斜杠有时可能仍然是合适的。

例如，长的多行的with语句不能用隐式续行，可以用反斜杠：

withopen（'/path/to/some/file/you/want/to/read'）asfile_1,\

open（'/path/to/some/file/being/written','w'）asfile_2:

file_2.write（file_1.read（））

另一种类似的情况是在assert语句中

确认恰当地缩进了延续的行

换行应该在二元操作符前面还是后面

几十年来推荐的风格是在二元操作符后换行。

但这会通过两种方式影响可读性:

操作符往往分散在屏幕的不同的列上,并且每个操作符都被移动到远离其操作数。

在这里,眼睛要做额外的工作看清哪些数是添加或减去:

#坏的:

操作符远离它们的操作数

income=（gross_wages+

taxable_interest+

（dividends-qualified_dividends）-

ira_deduction-

student_loan_interest）

为了解决这个可读性问题,数学家和出版商遵循相反的约定。

DonaldKnuth在他的《电脑和排版》系列中解释了传统规则:

“尽管后一段总是打破内公式二进制操作和关系,显示公式总是在二进制操作前换行”。

以下的数学运算传统通常可以使得结果更加具有可读性

#好的:

易于匹配操作数和操作符

income=（gross_wages

+taxable_interest

+（dividends-qualified_dividends）

-ira_deduction

-student_loan_interest）

#二元运算符首选的换行位置在操作符后面

classRectangle（Blob）:

def__init__（self,width,height,

color='black',emphasis=None,highlight=0）:

ifwidth==0andheight==0and\

color=='red'andemphasis=='strong'or\

highlight>100）:

raiseValueError（"sorry,youlose"）

ifwidth==0andheight==0and（color=='red'or

emphasisisNone）:

raiseValueError（"Idon'tthinkso--valuesare%s,%s"%

（width,height））

Blob.__init__（self,width,height,

color,emphasis,highlight）

在Python代码中,允许打破之前或之后一个二元运算符的规则,只要与当前惯例是一致的。

为新代码Knuth的风格。

空行

用两行空行分割顶层函数和类的定义.

类内方法的定义用单个空行分割.

额外的空行可被用于（保守的（sparingly））分割一组相关函数（groupsofrelatedfunctions）.

在一组相关的单句中间可以省略空行.（例如.一组哑元（asetofdummyimplementations））.

在函数中使用空行时,请谨慎的用于表示一个逻辑段落（indicatelogicalsections）.

Python接受contol-L（即^L）换页符作为空格;Emacs（和一些打印工具）视这个字符为页面分割符,因此在你的文件中,可以用他们来为相关片段（sections）分页。

注意，一些编辑器和基于Web的代码查看器可能不能识别control-L是换页，将显示另外的字形。

源文件编码

Python核心发布中的代码应该始终使用UTF-8（或Python2中用ASCII）。

文件使用ASCII（Python2中）或UTF-8（Python3中）不应有编码声明。

在标准库中，非默认编码仅用于测试目的或注释或文档字符串需要提及包含非ASCII字符的作者名；否则，使用\x，\u，\U，或\N是字符串中包含非ASCII数据的首先方式。

Python3.0及以上版本，为标准库（参见PEP3131）规定以下策略：

Python标准库中的所有标识符必须使用ASCII标识符，在可行的地方使用英文单词（在很多例子中，使用非英文的缩写和专业术语）。

另外，字符串和注释必须用ASCII。

仅有的例外是（a）测试非ASCII的特点，（b）测试作者名。

不是基于拉丁字母表的作者名必须提供一个他们名字的拉丁字母表的音译。

开源项目面向全球，鼓励采用统一策略。

导入

#通常应该在单独的行中导入（Imports）

importos

importsys

#这样也是可以的

fromsubprocessimportPopen,PIPE

Imports通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前.

Imports应该有顺序地成组安放.

•标准库的导入（Imports）

•相关的第三方导入（即,所有的email包在随后导入）

•特定的本地应用/库导入（imports）

•你应该在每组导入之间放置一个空行.

把任何相关all规范放在导入之后。

推荐绝对导入，因为它们更易读，并且如果导入系统配置的不正确（例如当包中的一个目录在sys.path的最后）它们有更好的表现（或者至少给出更好的错误信息）：

importmypkg.sibling

frommypkgimportsibling

frommypkg.siblingimportexample

明确的相对导入可以被接受用来替代绝对导入，特别是处理复杂的包布局时，绝对导入过于冗长。

from.importsibling

from.siblingimportexample

标准库代码应该避免复杂包布局并使用绝对导入。

隐式的相对导入应该永远不被使用，并且在Python3中已经移除。

从一个包含类的模块中导入类时，下面这样通常是好的写法：

frommyclassimportMyClass

fromfoo.bar.yourclassimportYourClass

#如果这种写法导致本地名字冲突，那么就这样写：

importmyclass

importfoo.bar.yourclass

#并使用“myclass.MyClass”和“foo.bar.yourclass.YourClass”来访问。

避免使用通配符导入（from<模块名>import*），因为这样就不清楚哪些名字出现在命名空间，这会让读者和许多自动化工具困惑。

通配符导入有一种合理的使用情况，重新发布一个内部接口作为一个公共API的一部分（例如，重写一个纯Python实现的接口，该接口定义从一个可选的加速器模块并且哪些定义将被重写提前并不知道）。

用这种方式重新命名，下面的有关公共和内部接口的指南仍适用。

字符串引号

Python中，单引号字符串和双引号字符串是一样的,本PEP不建议如此,建议选择一个并坚持下去。

当一个字符串包含单引号字符或双引号字符时，使用另一种字符串引号来避免字符串中使用反斜杠。

这可以提高可读性。

三引号字符串，总是使用双引号字符，与PEP257文档字符串规范保持一致。

表达式和语句中的空格

Guido不喜欢在以下地方出现空格

以下情况避免使用多余的空格

#紧挨着圆括号,方括号和花括号的

spam（ham[1],{eggs:

2}）

#紧贴在逗号,分号或冒号前的

ifx==4:

printx,y;x,y=y,x

#在切片中冒号像一个二元操作符，冒号两侧应该有相同数量的空格（把它看作最低优先级的操作符）。

#在一个扩展切片中，两个冒号必须有相等数量的空格。

#例外：

当一个切片参数被省略时，该空格也要被省略。

ham[1:

9],ham[1:

3],ham[:

3],ham[1:

]

ham[lower:

upper],ham[lower:

upper:

],ham[lower:

step]

ham[lower+offset:

upper+offset]

ham[:

upper_fn（x）:

step_fn（x）],ham[:

step_fn（x）]

ham[lower+offset:

upper+offset]

#紧贴着函数调用的参数列表前开式括号（openparenthesis）的

spam

（1）

#紧贴在索引或切片（slicing?

下标?

）开始的开式括号前的

dct['key']=lst[index]

#在赋值（或其它）运算符周围，不要为了与其他的赋值（或其它）操作符对齐，使用不止一个空格。

x=1

y=2

long_variable=3

其它建议

避免尾随空格。

因为它通常是无形的,它可能会让人很困惑:

如一个反斜杠,后跟一个空格和一个换行符不算作一行延续标记。

有些编辑器不保护它，并且许多项目（如CPython本身）导向钩子,拒绝它。

始终在这些二元运算符两边放置一个空格:

赋值（=）,比较（==,<,>,!

=,<>,<=,>=,in,notin,is,isnot）,布尔运算（and,or,not）.

如果使用了不同优先级的操作符，在低优先级操作符周围增加空格（一个或多个）。

不要使用多于一个空格，二元运算符两侧空格数量相等。

i=i+1

submitted+=1

x=x*2-1

hypot2=x*x+y*y

c=（a+b）*（a-b）

#不要在用于指定关键字参数或默认参数值的'='号周围使用空格,例如:

defcomplex（real,imag=0.0）:

returnmagic（r=real,i=imag）

#函数注释应该对冒号使用正常规则，并且，如果存在->，两边应该有空格

defmunge（input:

AnyStr）:

...

defmunge（）->AnyStr:

...

#结合一个参数注释和默认值时,在=符号两边使用空格（仅仅当那些参数同时有注释和一个默认值时）。

defmunge（sep:

AnyStr=None）:

...

defmunge（input:

AnyStr,sep:

AnyStr=None,limit=1000）:

...

#不要将多条语句写在同一行上.

iffoo=='blah':

do_blah_thing（）

do_one（）

do_two（）

do_three（）

#尽管有时可以将if/for/while和一小段主体代码放在一行，但在一个有多条子句的语句中不要如此。

避免折叠长行！

#最好不要

iffoo=='blah':

do_blah_thing（）

forxinlst:

total+=x

whilet<10:

t=delay（）

注释

同代码不一致的注释比没注释更差.当代码修改时,始终优先更新注释!

注释应该是完整的句子.如果注释是一个短语或句子,首字母应该大写,除非他是一个以小写字母开头的标识符（永远不要修改标识符的大小写）.

如果注释很短,最好省略末尾的句号。

注释块通常由一个或多个由完整句子构成的段落组成,每个句子都应该以句号结尾.

你应该在句末的句号后使用两个空格,以便使Emacs的断行和填充工作协调一致（译按:

应该说是使这两种功能正常工作,"."给出了文档结构的提示）.

用英语书写时,断词和空格是可用的.

非英语国家的Python程序员:

请用英语书写你的注释,除非你120%的确信这些代码不会被不懂你的语言的人阅读.

"""

我就是坚持全部使用中文来注释，真正要发布脚本工具时，再想E文的；

开发时每一瞬间都要用在思量中，坚决不用在E文语法，单词的回忆中！

--ZoomQUiet

约定使用统一的文档化注释格式有利于良好习惯和团队建议！

文档化开发注释规范

注释块

注释块通常应用于跟随着一些（或者全部）代码并和这些代码有着相同的缩进层次.注释块中每行以'#'和一个空格开始（除非他是注释内的缩进文本）.

注释块内的段落以仅含单个'#'的行分割.

行内注释

行内注释应该谨慎使用.

一个行内注释是和语句在同一行的注释.行内注释应该至少用两个空格和语句分开.它们应该以'#'和单个空格开始.

如果行内注释指出的是显而易见的，那么它就是不必要的。

#不要这样做：

x=x+1#增加x

#但有时，这样是有用的：

x=x+1#补偿border

文档字符串

应该一直遵守在PEP257中编写好的文档字符串（又名"docstrings"）的约定，

"""

DocumentationStrings--文档化字符;

为配合pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin语法,约定一些字符,

以便自动提取转化为有意义的文档章节等等文章元素!

--Zoomq

"""

为所有公共模块,函数,类和方法编写文档字符串.文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释.这个注释应该在"def"这行后.

PEP257描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的\"\"\"应该单独成行,例如:

"""Returnafoobang

Optionalplotzsaystofrobnicatethebizbazfirst.

"""

对单行的文档字符串,请保持结尾的"""在同一行.

版本注记

如果你要将RCS或CVS的杂项（crud）包含在你的源文件中,按如下做.

__version__="$Revision$"

#$Source:

/cvsroot/python_doc/pep8.txt,v$

这个行应该包含在模块的文档字符串之后,所有代码之前,上下用一个空行分割.

对于CVS的服务器工作标记更应该在代码段中明确出它的使用

如：

#文件：

$id$

#版本：

$Revision$

这样的标记在提交给配置管理服务器后，会自动适配成为相应的字符串，如：

#文件：

$Id:

ussp.py,v1.222004/07/2104:

47:

41hdExp$

#版本：

$Revision:

1.4$

----HD

命名约定

Python库的命名约定有点混乱,所以我们将永远不能使之变得完全一致---不过还是有公认的命名规范的.

新的模块和包（包括第三方的框架）必须符合这些标准,但对已有的库存在不同风格的,保持内部的一致性是首选的.

根本原则

用户可见的API的公开部分的名称，应该体现用法而不是实现。

描述:

命名风格

有许多不同的命名风格.以下的有助于辨认正在使用的命名风格,独立于它们的作用.

以下的命名风格是众所周知的:

•b（单个小写字母）

•B（单个大写字母）

•小写串如:

getname

•带下划的小写串如:

_getname,lower_case_with_underscores

•大写串如:

GETNAME

•带下划的大写串如:

_GETNAME,UPPER_CASE_WITH_UNDERSCORES

•CapitalizedWords（首字母大写单词串）（或CapWords,CamelCase/驼峰命名法--这样命名是由于它的字母错落有致的样子而来的.这有时也被当作StudlyCaps.如:

GetName

◦注意：

当CapWords中使用缩写，大写所有的缩写字母。

因此HTTPServerError优于HttpServerError。

•mixedCase（混合大小写串）（与首字母大写串不同之处在于第一个字符是小写如:

getName）

•Capitalized_Words_With_Underscores（带下划线的首字母大写串）（丑陋!

）

还有一种使用特别前缀的风格，用于将相关的名字分成组。

Python中很少这样用，但是出于完整性要提一下.

例如，os.stat（）函数返回一个元祖，它的元素名字通常类似st_mode，st_size，st_mtime等等这样。

（这样做是为了强调与POSIX系统调用结构体一致，这有助于程序员熟悉这些。

）

X11库的所有的公开函数以X开头。

Python中，这种风格通常认为是不必要的，因为属性名和函数名以对象名作前缀，而函数名以模块名作前缀。

另外,以下用下划线作前导或结尾的特殊形式是被公认的（一般可以与任何约定相结合）:

_single_leading_underscore（以一个下划线作前导）:

弱的"内部使用（internaluse）"标志.

（例如,"fromMimport*"不会导入以下划线开头的对象）.

single_trailing_underscore_（

展开阅读全文