《Python Coding Rule开发编码规范（中文版）.docx》由会员分享，可在线阅读，更多相关《Python Coding Rule开发编码规范（中文版）.docx（7页珍藏版）》请在taowenge.com淘文阁网|工程机械CAD图纸|机械工程制图|CAD装配图下载|SolidWorks_CaTia_CAD_UG_PROE_设计图分享下载上搜索。
1、Python Coding Rule开发编码规范（中文版）PythonCodingRule译盾Pyihun开发编码规范|1. Python开发编码规范1. Python开发编码规范1 .介绍2 .一致性的建议3 .代码的布局1 .缩进2 .制表符还是空格？3 .行的最大长度4 .空行5 .编码4 .导入5 .空格1 .其它建议6 .注释1 .注释块2 .行内注择7 .文档化8 .版本注记9 .命名约定1 .描述:命名风格2 .说明:命名约定1 .应防止的名字2 .模块名3 .类名4 .异常名5 .全局变量名6 .函数名7 .方法名和实例变量8 .继承的设计10.设计建议hoxide 初评 dr
2、eamingk 校对发布 040724xyb虫新揖版040915ZoomQuiet MoinMoin 美化 050610用Python进行开发时的编码风格约定原文:epes:PEP 008 ：?Style Guide for Python Code|l.1.介绍这篇文档所给出的编码约定适用F在主要的Python发布版本中组成标准库的Python代码.清杏阅相 关的关于在Python的C实现中C代码风格指南的描述.这篇文档改编自Guido最初的Python风格指南一文.并从Barrys style guide1中添加了局部内 容.在有冲突的地方,Guide的风格规那么应该是符G本PEP的意图(译
3、注:就是容有冲突时，应以 Guidokl格为准)这篇PEP也许仍然尚未完成(实际匕它可能永远不会结束).11.2. 一致性的建议愚叁得使用一致性是无知的妖怪(A Foolish Consistency is the Hobgoblin of Little Minds)呆板的坚持一致性是傻的没边f!Zoomq在这篇风格指导中的一致性是重要的.在一个工程内的致性更重要.在个模块或函数内的一致 性最重要.但最但要的是:知遒何时会不 致-仃时只是没有实施风格指导.当出现疑惑时,运用你的此件刘断.乔韦别的例子.然后决丁怎样看起来田好.井IT要不即下口 !打破一条堀定规那么的两个好理由；I.当应用这个规那
4、么是将导致代玛可洗性卜降,即便对某人来说，他己”.习惯按这条规贝J来阅读代码了.2.为了和周围的代码保持 致而打破规那么(也许是历史原因) -虽然这也是个清除其它混乱的好机会(真正的XP风格). 1.3.代码的布局(Code lay-out)11.3.1.缩进(Indentation)使用Emacs的Python-mode的默认值:4个空格一个缩进层次对于确文古老的代码.你不希望产生混乱.可以继续使用8空格的制表符 (8-space tabs). Emacs Python-mode自动发现文件中主要的缩进层次，依此设定缩进参数. 1.3. 2.制表符还是空格？(Tabs or Spaces)永
5、远不要混用制表符和空格.最流行的Python缩进方式是仅使用空格.其次是仅使用制表符.混合着制衣符和空格缩进的代码将被转换 成仅使用空格.(&En】acs中.选中整个缓冲区，按ESC-x去除制及符(unlabify).)调用pylhon命令行解糕心IH使用-t选项，可对代码中不合法 得混合制表符和空格发出苦告(warnings).使用时警告(warnings)将变成错误(errors).这些选项是被高度推荐的.对于新的工程,强烈推荐仅使用空格(spaces-only)而不是制表符.许多编辑器拥有使之易于实现的功能.(在Emacs中.确认indent-labs- mode 是 nil).l.3.
6、3.行的最大长度(Maximum Line Length)周围仍然有许多设备被限制在每行80字符;而且，窗口限制在80个字符使将多个窗口并排放置成为可能.在这些设备上使用默认的折桂 (wrapping)方式看起来仃点.队因此，诂必所仃行限制在最大79字符(Enuics准确得将行限制为长80字符),对顺序持放的大块文本(文 档字符串曲E释),推荐将长度限制在72字符.折叠长行的首选方法是使用Pyhon支持的Bl括号,方括号(brackets)和花括号(braces)内的行延续.如果需要，你可以方法达式周围增加 时额外的阿括号,但是小时仲用反余I札看北光更好.确认恰当得缩进f延续的行.Emacs的
7、Python-modeF确得完成这些.一些例子：Toggle line numbers1 class Rectangle(Blob):2 def _init_(self, width, height,color=,black, Gmphasis=NonG, highlight ):if width - 0 and height - 0 and color , red and emphasis - strong or highlight 100:6raise ValueError, sorry, you lose1*if width = 0 and height = 0 and (color =
8、 red* oremphasis is None):8raise ValueError, I don * t think soBlob.init(self, width, height,11color, emphasis, highlight)11.3. 4.空行(Blank Lincs)用两行空行分割顶层函数和类的定义.类内方法的定义用单个空行分割.额外的空行可被用上(保守的(sparingly)分割相关因数组成的 lr?(gr()ups of related functions).在一组相关的单旬中间可以省略空行.(例如,组附元(a set of dummy implementations
9、).当空行用于分割方法(method)的定义时,在das(行和第个方法定义之间也要有个空行.在函数中使用空行吐而革慎的用上衣示一个逻51段落(indicale logical sections).Python接受contol-L(即换页符作为空格:Emacs的些打印具)视这个字符为页而分割符因此在你的文件中,可以用他们来为相 美片,段(sections)分页. 1.3.5.编码(Enc(Mlings)epes:(PEP 263)Python核心发布中的代码必须始终使用ASCII或Latin-1编6W(又名ISO-8859-1).使用ASCII的文件不必有译码cookie(coding cook
10、ie).Lalin-1仅与注样或文档字符串涉及作柠名字需要Lalin-1时力被使用：另外使用x转义字符足在字符串中包含I ASCII(non-ASCII)数据的小娩方法，作为PEP263实辨代秒的测试焚传的局部丈仲是个例外.Python 2.4以后内核支持Unicode /!不管什么情况使用UTF-8吧！这是|：道！ZoomQuiet(1.4.导入(Imports)通常应该在单独的行中导入(Imports),例如:No: import sys, os Yes: import sys import os但足这样也是可以的:from types import StringTyp, ListType
11、 Imports通常被放置在文件的顶部.仅在模块注样和文档字符串之后：模块的全局变L；和常置之前.Impon、应该有顺序地成组安放.1 .标准库的导入(Imports )2 .相关的I包(major package)(fj导入(即，所仃的email包在随后导入)3 .特定应用的导入(imports) 你应该在每组，入之间放苴个空行. 对内部包的导入是不推荐使用相对甘入的.对所有导入都要使用包的绝对路役. 从个包含类的模块中牙人类时.通常可以写成这样：from MyClass import MyClass from foo.bar.YourClass import YourClass如果这样写导
12、致了本地名字冲突.那么就这样写import MyClass即使用用yClass. MyClass”和和oo. bar. YourClass. YourClass”|l.5.空格(Whitespace in Expressions and Statements)Guido不喜欢在以F地方出现空格:“spam( ham. 1 , eggs: 2)”. Always write this as *spam(haml, (eggs: 2)”.o紧挨着圆括号，方括号和花括号的，如:spa* hand 1 , eggs: 2 )”.要始终将它丐成spam(haml, eggs: 2)”.*if x = 4
13、 : print x , y ; x , y = y , x”. Always write 山is as “if x = 4: print x, y; x, y = y, x”. o紧贴在逗号，分号或冒号前的.如:if x = 4 : print x , y ; x , y = y , x.要始终将它写成ix = 4: print x, y; x, y = y, x.紫贴着函数调用的参教列表前开式括耳(open parenlhcsis )的，如(1)要始终：将它;成1)”.slicing, as in: dietkey = 1 ist index”. Always write this as
14、*dict 7 key* = listfindexK.紧贴4索”或切片(slicing?卜.标?)开始的开式括，；前的，如：diet key = list index”.要始终将它写成diet key = list index*.。在赋值(或其它)运算符周网的用广和其它并排的一个以I.的空格，如:Toggle line numbers1 x= 12 y- 2long_variable = 3要始终将它写成Toggle line numbers1 x - 12 y = 2lonq_variable = 3(不要对以上任意一条和他争论-Guido养成这样的风格超过20年了.)(Other Reco
15、mmendations)始终在这些.元运算符两边放置个空格:赋值(=),比拟(=,.!=, o. =, in, not in, is, is not).布尔运算(and, or, not).*按你的看法在克术运算符周围插入空格.始终保持二元运算符两边空格的一致.Toggle line numbers123456 一些例子：i = i+i submitted = submitted + 1 x = x*2 - 1 hypot2 - x*x + y*y c = (a-rb) * (a-b) c (a b) (a - b)不要在用，指定关键？参数或默认参数值的七号周阳使用空格、例如:Toggle l
16、ine numbersdef complex(real, imaq=.): return magic(r=real, i=imag)不要将多条语句写在同一行匕No: if foo = blah: do_blah_thing()Yes: if foo = blah:do_blah_thing()No: do_one(); do_two(); do_three()Yes: do_one()do_two()do_three()（1.6.注释（Comments）同代码不致的注代比没注样更差.当代64修改时，始终优先更新注糕!注释应该是完整的句子.如果注释是一个短语或句子.首字母应该大写，除北他是一个以
17、小写字母开头的标识符（永远不要修改标识符 的大小写）.如果注释很短.最好省略末尾的句号（period?结尾句末的停顿?也可以是逗号吧.）注释块通常由一个或多个由完整句子构成的段落组成. 一个句广应该以句号结尾.你应该在句末.句号后使用两个空格,以便使Emacs的断行和填充工作协调一致（译按:应该说是使这两种功能正常匚作二”给出了文档 结构的提示）.用英语书写时.断词和空格是可用的.IE英语国家的Python程挣员:请用英语书写你的注释，除非你120%确实信这些代码不会被不懂你的语齐的人阅读.我就止忖）全部使用中文火注样，真正要发布脚本I典时，再想E文的: 开发时每T间都婴用在思吊:中,里决不用
18、在E文语法，单词的回忆中!ZoomQUiet约定使用统的文档化注择格式有利良好习惯和团队建议！ -CodcComnicnlingRuk: 注释块（Block Comments）注释块通常应用于跟随着一些（或者全部）代码并和这拽代码有着相同的前进层次,注释块中每行以#和一个空格开始（除非他是注择 内的缩进文本）.注释块内的段落以仅含单个宣的行分割.注释块上卜方最好有一空行包围（或上方两行卜一方-行，时一个新函数定义段 的注释）. 1.6.2.行内注释（Inline Comments） （inline?内联?翻成“行内比拟好吧）一个行内注样是和语旬在同行的注释.行内注糕应该灌慎适用.行内注应该至少
19、用两个空格和语句分开.它们应该以法和单 个空格开始.x = xi-1P Increrer.t x如札吕意是很明广的州:么行内注很是不必要的，事实上是应该被去掉地.不要这样写:X = *!# IlK EHFHl I. Xx - x4-lt Compensate f:r border但是有时，这样是行益的：x , x-f 1H Compensate for border|1.7.文档化（Documentation Strings）Conventions for writing good documentalion strings （a.k.a. dixrslrings） arc inmiorlal
20、ized in cpc、:PEP 257. 应该一直遵守编写好的文档字符字乂名docslrings）的约定（?实在不知道怎么译）Documentation Strings-文档化字符；为间合pydoc;cpydoc, DoxygonS号文档化工具的使用，类似仪。inMo in诲法，约定一*字符，以便自动提取转化为有意义的文档章8等等文章儿素！为所仃公共模块.函数.类和方法编写文档字符中.文档字符串对非公开的方法不是必要的.但你应该有个描述这个方法做什么的注 释.这个注释应该在在e这行后.cp“PEP257描述了好的文档字符印的约定.定注意.多行文档字符中结尾的应该单独成行.例如：Return
21、a foobangOptional plotz says to frobnicate the bizbaz first.对单行的文档字符符，结尾的在同行也可以.实际上Python白小山就便用文I,讹编码维8展所闫内置有象的假用说检J不信的话常试：Ipython import time dir(time)_doc_*, *_file_*, _name_, * accept2dyear *, *alt2one*, *asctime, clock, ctime *, daylight, ,gmt ime , localtime *, niktime, sleep, strftime, strptim
22、e, struct_time, * time *, * timezone, tzname, tzset help(time.time)Help on built-in function time in module time:time(.)time() - floating point numberReturn the current time in seconds since the Epoch.Fractions of a second may be present if the system clock provides them.(1.8.版本注记(Version Bookkeepin
23、g)(我觉得叫注记更好) 如果你要将RCS或CVS的杂项(crud)包含在你的源文件中，按如下你.Toggle line numbers_version_ = $Revision: 1.4 $-2H $Source: E:/evsroot/python_doc/pep8.txt,v $这个行应该包含在模块的文档字符中之后，所彳J.代码之前上下用个空行分刑.对尸CVS的眼务海T作标记更应该在代码段中明确出它的使用如：在文档献开始的版权声明后应加入如卜版本标记：# 文件：$id$# 版本：$Revision$这样的标记在提交给配置管理服务器后，会自动通品成为相应的字符中,如: 文件：$Id: us
24、sp.py,v 1.22 2004/07/21 04:47:41 hd Exp $# 版本： $Revision: 1.4 $HD|l.9.命名约定（Naming Conventions）Python库的命名约定有点混乱,所以我们将永远不能使之变得完全致不过还是有公认的命名规范的.新的模块和包（包括第三方的 框架）必须符合这些标准，但对已有的库存在不同风格的，保持内部的一致性是首选的.1.9.1.描述:命名风格（Descriptive: Naming Styles）有许多不同的命名风格.以卜的有助J识别正在使用的命名风格，独立于它们的作用.以下的命名风格是众所周知的： b （单个小写字母） B
25、 （单个大写字母） 小写串如:getname 带下划的小写;|l tol:_gelname 大写串如:GETNAME 带卜划的大写小如:_GETNAME CapilalizedWords（首字母大写单词串）（或C叩Words. CamelCase -这样命名是由于它的字母错落有致的样子而来的.这仃时也被当作StudlyCaps.如:GelNamc mixedCase （混合大小写串）（与首字母大写串不同之处在于第一个字符是小写如:gelName） Capitalized_Words_With_Underscores（*r|j 卜划线的门字母大写申）（H.陋!）还价一种使用特别前缀的风格，用于将
26、相关的名字分成组.这在Python中不常用,但.是出于完整性要提一下.例如6.siai（）函数返回 个tuple,他的元素传统上仃象sl_mode. st_size. st_mliine等经这样的名字.XI 1库的所仃公开函数以X开头.（4：Pythoni|i,这个风格通常认 为是不必要的，因为属性和方法名以对象作前缀.而函数名以模块名作前缀.）另外.以卜用F划线作前导或结尾的特殊形式是被公认的（这些通常可以和任何习惯组合（使用?）： _singleeading_underscore（以一个下划线作前导）:弱的呐部使用（internal use）”标志.-（例如,from M import *
27、不会导入以卜,划线开头的对象）. single_tiailing_imderscore_（以 个卜戈，纹结兄）:用于防止叮Pylhcn美淀词的冲突，例如.o Tkinter.TopleveKmaster. class_=ClassNaireT. dou31c_lea（Jing_jncerscore（Xx 卜划线）：从Pyihon 1.4起为类私仃名. double leading and 11 ,ii 1 ing underscore:特殊的（magic）对象或域性.存用户控制的（uscr-conlrollcd）名字空间，例如： init , _import或_fi le_ .有时它们被用户定
28、义JF于触发某个特殊行为（magic behavior）（例如:运算符重载）:有时被构造器 （infrawucturc）插入.以便2使用或为了调试.因此在未来的版本中、构造瑞（松放谷定义为Python解驿器和标准库）可能打算建。：自己 的魔法属性列表，用户代码通常应该限制将这种约定作为己用.欲成为构造器的一局部的用户代码可以在F滑线中结合使用短前缀，例 如. bobo nuigic_attr 1.9. 2.说明：命名约定（Prescriptive: Naming Conventions）1.9.2.1, 应防止的名字（Names to Avoid）永远不要用字符1（小写字母el（就是读音.卜.
29、同）.O（大写字母oh）,或“大写字母eye）作为单字符的变尻名.在某些字体中，这些字符不 能与数字1和0分开.当想要使用T时，用。代替它.1.9. 2. 2.模块名（Module Names）模块应该是不含下划线的.简短的.小写的名字.因为模块名被映射到文件名，有些文件系统大小写不敏感并且被短长名字，模块名被选为相当短是重要的一这在Unix上不是问题，但 当代码传到Mac或Windows上就可能是个问题了.节一个用C或C+写的扩展模块有个伴随的Python模块，这个Pylhon模块提供了一个更高层（例如，更而向对象）的接口时.C/C+模块有一个前导下划线（如：_socket）Python包应
30、该是不含卜.划线的，简短的，全小写的名字.1.9. 2. 3.类名（Class Names）几乎没有例外,类名总是使用首字母大写单词串（CapWords）的约定.|l.9. 2. 4.异常名（Exception Names）如果模块对所仃情况定义了单个异常.它通常被叫做“error“或Error”,似乎内建（扩展）的模块使用error（例如:os.error）.而Python模块通 常用Error（例如:xdrlib.Error）.趋势似乎是货向使用CapWords异常名.1.9. 2. 5,全局变量名（Global Variable Names）（让我们希望这些变：式打算只被用模块内部）这些
31、约定。那些用于函数的约定差不多.被设计可以通过“from M import ”来使用的那些模块,应该在那此不想被导入的全局变量（还有内部函数和类）前加个下划线）.19. 2. 6.函数名（Function Names）函数名应该为小写.可.能用口划线风格单词以增加可读性.mixedCase仅被允许用于这种风格已经占优势的I： F文（如：由reading.py）以 便保持向后兼容.1.9. 2. 7.方法名和实例变量（Method Names and Instance Variables）这段大体上和函数相同:通常使用小写单词，必要时用F划线分隔增加可读性.使用一个前导下划线仅用丁不打作为类的公
32、共接口的内部方.法和灰例变缸.Pylhon不强制要求这样；它取决了程序员是否遵守这个 约定.使用两个前导下划线以发示类私有的名字.P）#on将这些名字和类名连接布一起：如果类Foo行 个属性名为 人它不能以F。. a访 何.（执著的用户（An insistent user）还是可以通过Foo. F。一a得到访问权.）通常,双前导卜划线应该只用来防止与类（为可以类化所设计)中的属性发生名字冲突.1.9. 2. 8.继承的设计(Designing for inheritance)始终要确定个类中的方法和文例变址是台要:被公开.通常.永远不要将数据变量公开，除非你实现的本质上只是汕泉.人们总是更沐
33、欢给类提供一个函数的接口作为替换(Python 2.2的一些开发者在这点上做得非常漂亮).同样，确定你的属性是否应为私有的.私有与IE公有的区别在：前者永远不会被用在个派生类中，而后者可能会.是的，你应该在大脑 中就用继承设计好了你的类.私有属性必须仃两个前导卜划线.无后置卜.划线.出公有属性必须有一个前导下划线，无后置下划线.公共属性没有前导和后置卜划线.除I陀们。保照字冲突，在此情况卜，单个后置卜划线比前置或混乱的拼写要好.例如:class.优产 klass.最后一点有些小议：如果相比class.你更京欢klass,那么这只是一致性问题.|l.1O.设计建议(Programming Rec
34、ommendations)同象None之类的单值进行比拟，应该永远用工，或为n”来做.当你本意是if x is not None”时.对写成“if x”要小心-例如当你测试一个 默认为None的变量或参数是否被设置为其它值时,这个其它值可能是一个在布尔上下文中为假的值!基于类的异常总是好过基于字符串的异常.模块和包应该定义它们自己的域内特定的基异常类(base exception class).基类应该是内建 的Exceplion类的类.还始终包含一个类的文档字符中.例如:Toggle line numbersclass MessageError(Exception):2Base class
35、for errors in the email package.wn使用字符申方法(mclhods)代杵字符串模块.除井必须向后兼容Python 2.0以前的版本,字符串方法总是“常快,而11和Unicode字符串共 用同样的API(应用程序接口)住检查前缀或前缀时防止对字符串进行切)V.用slartswilhO和endswilh。代替,因为它们是明确的并且错误更少.例如：No: if foo:3 = bar:Yes: _i l jq. s ci,bat ):例列2M果你的代码必须工作在Pylhun 1.5.2 (见我们希中它不算发生!).对象类型的比校应该始终用isinstance/C皆直接
36、比拟类型例如：Ho: if typeiobj) is type1):Yes: if isiii3ini):琉3 f ?软是壬是？初小时.紧记它也l能是unicele字符;I；!在Pyihm 2.工Nr凡i nicodV公共的工:英,bzwtringj斤以你u：以这斗滋 Toggle 1 nc numbersi f iomotonc3t ob j t oaooat-xng);在Pytivn2.2类型模块为此定义Sirin订ypes类也例如:Toggle line numbersfrom types import StringTypes2if isinstance(obj, StringTypes
37、):在Python 2.0和2.1.你应该这样做：Toggle line numbersfrom types import StringType, UnicodeType2if isinstanceobjr ScrinqType) or isinstance(obj, UnlcodeType):对序列,(列符串(strings)冽表元组(luples),使用空列表是false这个J；实，因此if not seq或if seq比if len(seq)i,kif not len(seq) 好.书写字符串文字时不要依赖于行意义的后置空格.这种后置空格在视觉上是不可区分的,并且有些编辑器(特别是近来.reindcnt.py)会 将它们修整掉.不要用=来比拟布尔型的值以确定是True或False(布尔里是Pylhn 2.3中新增的)No: if greeting = True：Yes: i greeting:No: if greeting True:Yes: if greeting:ZoomQuiet (2(X)5-01-26)Iasi cdiicd 2005-06-17 02:48:56 by ZoomQuiet