Python开发编码规范.docx
- 文档编号:8130093
- 上传时间:2023-01-29
- 格式:DOCX
- 页数:13
- 大小:25.04KB
Python开发编码规范.docx
《Python开发编码规范.docx》由会员分享,可在线阅读,更多相关《Python开发编码规范.docx(13页珍藏版)》请在冰豆网上搜索。
Python开发编码规范
Python开发编码规范
1代码的布局3
1.1缩进3
1.2制表符还是空格?
3
1.3行的最大长度3
1.4空行3
2编码4
2.1导入4
2.2空格5
2.3其它建议(OtherRecommendations)6
2.4注释7
2.4.1注释块7
2.4.2行内注释7
2.5文档化8
2.6版本注记9
2.7命名约定9
2.7.1描述:
命名风格10
2.7.2说明:
命名约定11
2.7.3应避免的名字11
2.7.3.1模块名(ModuleNames)11
2.7.3.2类名(ClassNames)11
2.7.3.3异常名(ExceptionNames)11
2.7.3.4全局变量名(GlobalVariableNames)12
2.7.3.5函数名(FunctionNames)12
2.7.3.6方法名和实例变量(MethodNamesandInstanceVariables)12
2.7.3.7继承的设计(Designingforinheritance)12
3设计建议(ProgrammingRecommendations)14
1代码的布局
1.1缩进
使用Emacs的Python-mode的默认值:
4个空格一个缩进层次。
对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-spacetabs)。
EmacsPython-mode自动发现文件中主要的缩进层次,依此设定缩进参数。
1.2制表符还是空格?
永远不要混用制表符和空格。
最流行的Python缩进方式是仅使用空格,其次是仅使用制表符。
混合着制表符和空格缩进的代码将被转换成仅使用空格。
(在Emacs中,选中整个缓冲区,按ESC-x去除制表符(untabify)。
)调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告(warnings)。
使用-tt时警告(warnings)将变成错误(errors)。
这些选项是被高度推荐的。
对于新的项目,强烈推荐仅使用空格(spaces-only)而不是制表符。
许多编辑器拥有使之易于实现的功能。
(在Emacs中,确认indent-tabs-mode是nil)。
1.3行的最大长度
周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符使将多个窗口并排放置成为可能。
在这些设备上使用默认的折叠(wrapping)方式看起来有点丑陋。
因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符),对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符。
折叠长行的首选方法是使用Pyhon支持的圆括号,方括号(brackets)和花括号(braces)内的行延续。
如果需要,你可以在表达式周围增加一对额外的圆括号,但是有时使用反斜杠看起来更好。
确认恰当得缩进了延续的行。
Emacs的Python-mode正确得完成了这些。
一些例子:
Togglelinenumbers
1 classRectangle(Blob):
2
3 def__init__(self,width,height,
4 color='black',emphasis=None,highlight=0):
5 ifwidth==0andheight==0and\
color=='red'andemphasis=='strong'or\
highlight>100:
6 raiseValueError,"sorry,youlose"
7 ifwidth==0andheight==0and(color=='red'or
8 emphasisisNone):
9 raiseValueError,"Idon'tthinkso"
10 Blob
。
__init__(self,width,height,
11 color,emphasis,highlight)
1.4空行
用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割。
额外的空行可被用于(保守的(sparingly))分割相关函数组成的群(groupsofrelatedfunctions)。
在一组相关的单句中间可以省略空行。
(例如。
一组哑元(asetofdummyimplementations))。
当空行用于分割方法(method)的定义时,在'class'行和第一个方法定义之间也要有一个空行。
在函数中使用空行时,请谨慎的用于表示一个逻辑段落(indicatelogicalsections)。
Python接受contol-L(即^L)换页符作为空格;Emacs(和一些打印工具)视这个字符为页面分割符,因此在你的文件中,可以用他们来为相关片段(sections)分页。
2编码
Python核心发布中的代码必须始终使用ASCII或Latin-1编码(又名ISO-8859-1)。
使用ASCII的文件不必有译码cookie(codingcookie)。
Latin-1仅当注释或文档字符串涉及作者名字需要Latin-1时才被使用;另外使用\x转义字符是在字符串中包含非ASCII(non-ASCII)数据的首选方法。
作为PEP263实现代码的测试套件的部分文件是个例外。
Python2。
4以后内核支持Unicode了!
不论什么情况使用UTF-8吧!
2.1导入
通常应该在单独的行中导入(Imports),例如:
No:
importsys,os
Yes:
importsys
importos
但是这样也是可以的:
fromtypesimportStringType,ListType
Imports通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前。
Imports应该有顺序地成组安放。
1。
标准库的导入(Imports)
2。
相关的主包(majorpackage)的导入(即,所有的email包在随后导入)
3。
特定应用的导入(imports)
你应该在每组导入之间放置一个空行。
对于内部包的导入是不推荐使用相对导入的。
对所有导入都要使用包的绝对路径
。
从一个包含类的模块中导入类时,通常可以写成这样:
fromMyClassimportMyClass
fromfoo。
bar。
YourClassimportYourClass
如果这样写导致了本地名字冲突,那么就这样写
importMyClass
importfoo。
bar。
YourClass
*
即使用"MyClass。
MyClass"和"foo。
bar。
YourClass。
YourClass"
2.2空格
(WhitespaceinExpressionsandStatements)
*Guido不喜欢在以下地方出现空格:
*
"spam(ham[1],{eggs:
2})"。
Alwayswritethisas"spam(ham[1],{eggs:
2})"。
o
紧挨着圆括号,方括号和花括号的,如:
"spam(ham[1],{eggs:
2})"。
要始终将它写成"spam(ham[1],{eggs:
2})"。
"ifx==4:
printx,y;x,y=y,x"。
Alwayswritethisas"ifx==4:
printx,y;x,y=y,x"。
o紧贴在逗号,分号或冒号前的,如:
"ifx==4:
printx,y;x,y=y,x"。
要始终将它写成"ifx==4:
printx,y;x,y=y,x"。
o
紧贴着函数调用的参数列表前开式括号(openparenthesis)的,如"spam
(1)"。
要始终将它写成"spam
(1)"。
slicing,asin:
"dict['key']=list[index]"。
Alwayswritethisas"dict['key']=list[index]"。
o紧贴在索引或切片(slicing?
下标?
)开始的开式括号前的,如:
"dict['key']=list[index]"
。
要始终将它写成"dict['key']=list[index]"。
o在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格,如:
Togglelinenumbers
1 x =1
2 y =2
3 long_variable=3
*要始终将它写成
Togglelinenumbers
1 x=1
2 y=2
3 long_variable=3
*(不要对以上任意一条和他争论---Guido养成这样的风格超过20年了。
)
2.3其它建议(OtherRecommendations)
始终在这些二元运算符两边放置一个空格:
赋值(=),比较(==,<,>,!
=,<>,<=,>=,in,notin,is,isnot),布尔运算(and,or,not)。
*按你的看法在算术运算符周围插入空格。
始终保持二元运算符两边空格的一致。
*一些例子:
Togglelinenumbers
1 i=i+1
2 submitted=submitted+1
3 x=x*2-1
4 hypot2=x*x+y*y
5 c=(a+b)*(a-b)
6 c=(a+b)*(a-b)
*不要在用于指定关键字参数或默认参数值的'='号周围使用空格,例如:
Togglelinenumbers
1 defcomplex(real,imag=0
。
0):
2 returnmagic(r=real,i=imag)
*不要将多条语句写在同一行上。
No:
iffoo=='blah':
do_blah_thing()
Yes:
iffoo=='blah':
do_blah_thing()
No:
do_one();do_two();do_three()
Yes:
do_one()
do_two()
do_three()
2.4注释
(Comments)
*同代码不一致的注释比没注释更差。
当代码修改时,始终优先更新注释!
注释应该是完整的句子。
如果注释是一个短语或句子,首字母应该大写,除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写)。
如果注释很短,最好省略末尾的句号(period?
结尾句末的停顿?
也可以是逗号吧,)注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾。
你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致(译按:
应该说是使这两种功能正常工作,"。
"给出了文档结构的提示)。
用英语书写时,断词和空格是可用的。
非英语国家的Python程序员:
请用英语书写你的注释,除非你120%的确信这些代码不会被不懂你的语言的人阅读。
我就是坚持全部使用中文来注释,真正要发布脚本工具时,再想E文的;
开发时每一瞬间都要用在思量中,坚决不用在E文语法,单词的回忆中!
--ZoomQUiet
*
约定使用统一的文档化注释格式有利于良好习惯和团队建议!
--CodeCommentingRule
2.4.1注释块
(BlockComments)
*注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次。
注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本)。
注释块内的段落以仅含单个'#'的行分割。
注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释)。
2.4.2行内注释
(InlineComments)
*(inline?
内联?
翻成"行内"比较好吧)
o一个行内注释是和语句在同一行的注释。
行内注释应该谨慎适用。
行内注释应该至少用两个空格和语句分开。
它们应该以'#'和单个空格开始。
x=x+1 #Incrementx
*如果语意是很明了的,那么行内注释是不必要的,事实上是应该被去掉的。
不要这样写:
x=x+1 #Incrementx
x=x+1 #Compensateforborder
*但是有时,这样是有益的:
x=x+1 #Compensateforborder
2.5文档化
(DocumentationStrings)
*Conventionsforwritinggooddocumentationstrings(a。
k。
a。
"docstrings")areimmortalizedin
PEP257。
应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?
实在不知道怎么译)
DocumentationStrings--文档化字符;
为配合pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin语法,约定一些字符,
以便自动提取转化为有意义的文档章节等等文章元素!
--Zoomq
*为所有公共模块,函数,类和方法编写文档字符串
。
文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释。
这个注释应该在"def"这行后。
*
PEP257描述了好的文档字符串的约定。
一定注意,多行文档字符串结尾的"""应该单独成行,例如:
"""Returnafoobang
Optionalplotzsaystofrobnicatethebizbazfirst。
"""
*对单行的文档字符串,结尾的"""在同一行也可以。
实际上Python自个儿就使用文档化编码维护着所有内置对象的使用说明\
不信的话常试:
#python
>>>importtime
>>>dir(time)
['__doc__','__file__','__name__','accept2dyear','altzone','asctime','clock','ctime','daylight','gmtime','localtime','mktime','sleep','strftime','strptime','struct_time','time','timezone','tzname','tzset']
>>>help(time。
time)
Helponbuilt-infunctiontimeinmoduletime:
time(。
。
。
)
time()->floatingpointnumber
ReturnthecurrenttimeinsecondssincetheEpoch。
Fractionsofasecondmaybepresentifthesystemclockprovidesthem。
2.6版本注记
(VersionBookkeeping)(我觉得叫"注记"更好)
*如果你要将RCS或CVS的杂项(crud)包含在你的源文件中,按如下做
。
Togglelinenumbers
1 __version__="$Revision:
1。
4$"
2 #$Source:
E:
/cvsroot/python_doc/pep8。
txt,v$
*这个行应该包含在模块的文档字符串之后,所有代码之前,上下用一个空行分割。
对于CVS的服务器工作标记更应该在代码段中明确出它的使用
如:
在文档的最开始的版权声明后应加入如下版本标记:
#文件:
$id$
#版本:
$Revision$
这样的标记在提交给配置管理服务器后,会自动适配成为相应的字符串,如:
#文件:
$Id:
ussp。
py,v1。
222004/07/2104:
47:
41hdExp$
#版本:
$Revision:
1。
4$
----HD
2.7命名约定
*Python库的命名约定有点混乱,所以我们将永远不能使之变得完全一致---不过还是有公认的命名规范的。
新的模块和包(包括第三方的框架)必须符合这些标准,但对已有的库存在不同风格的,保持内部的一致性是首选的。
2.7.1描述:
命名风格
*有许多不同的命名风格。
以下的有助于辨认正在使用的命名风格,独立于它们的作用。
以下的命名风格是众所周知的:
*b(单个小写字母)
*B(单个大写字母)
*小写串如:
getname
*带下划的小写串如:
_getname
*大写串如:
GETNAME
*带下划的大写串如:
_GETNAME
*
CapitalizedWords(首字母大写单词串)(或CapWords,CamelCase--这样命名是由于它的字母错落有致的样子而来的。
o
这有时也被当作StudlyCaps
。
如:
GetName
*mixedCase(混合大小写串)(与首字母大写串不同之处在于第一个字符是小写如:
getName)
*Capitalized_Words_With_Underscores(带下划线的首字母大写串)(丑陋!
)还有一种使用特别前缀的风格,用于将相关的名字分成组。
这在Python中不常用,但是出于完整性要提一下。
例如,os。
stat()函数返回一个tuple,他的元素传统上有象st_mode,st_size,st_mtime等等这样的名字。
X11库的所有公开函数以X开头。
(在Python中,这个风格通常认为是不必要的,因为属性和方法名以对象作前缀,而函数名以模块名作前缀。
)另外,以下用下划线作前导或结尾的特殊形式是被公认的(这些通常可以和任何习惯组合(使用?
)):
*_single_leading_underscore(以一个下划线作前导):
弱的"内部使用(internaluse)"标志。
o(例如,"fromMimport*"不会导入以下划线开头的对象)。
*single_trailing_underscore_(以一个下划线结尾):
用于避免与Python关键词的冲突,例如。
o
"Tkinter。
Toplevel(master,class_='ClassName')"。
*
__double_leading_underscore(双下划线):
从Python1。
4起为类私有名。
*
__double_leading_and_trailing_underscore__:
特殊的(magic)对象或属性,存在于用
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Python 开发 编码 规范