TableOfContents

Python Coding Rule

  --- hoxide 初译 dreamingk 校对发布 040724
  --- xyb 重新排版 040915
  --- ZoomQuiet MoinMoin 美化 050610

介绍

• 这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python 代码.请查阅相关的关于在Python的C实现中C代码风格指南的描述. 这篇文档改编自Guido最初的《Python风格指南》一文. 并从《Barry's style guide》中添加了部分内容. 在有冲突的地方，Guide的风格规则应该是符合本PEP的意图 (译注：就是当有冲突时，应以Guido风格为准) 这篇PEP也许仍然尚未完成(实际上，它可能永远不会结束).

一致性的建议

愚蠢得使用一致性是无知的妖怪(A Foolish Consistency is the Hobgoblin of Little Minds) {{{呆板的坚持一致性是傻的没边了! -- Zoomq}}}

• 在这篇风格指导中的一致性是重要的. 在一个项目内的一致性更重要. 在一个模块或函数内的一致性最重要. 但最重要的是:知道何时会不一致 -- 有时只是没有实施风格指导.当出现疑惑时,
  • 运用你的最佳判断.看看别的例子,然后决定怎样看起来更好.并且要不耻下问!

• 打破一条既定规则的两个好理由:
  1. 当应用这个规则是将导致代码可读性下降,即便对某人来说,他已经习惯于按这条规则来阅读代码了.
  2. 为了和周围的代码保持一致而打破规则(也许是历史原因)
     • -- 虽然这也是个清除其它混乱的好机会(真正的XP风格).

代码的布局

(Code lay-out)

缩进

(Indentation)

• 使用Emacs的Python-mode的默认值:4个空格一个缩进层次. 对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-space tabs). Emacs Python-mode自动发现文件中主要的缩进层次,依此设定缩进参数.

制表符还是空格?

(Tabs or Spaces)

• 永远不要混用制表符和空格. 最流行的Python缩进方式是仅使用空格, 其次是仅使用制表符.混合着制表符和空格缩进的代码将被转换成仅使用空格. (在Emacs中,选中整个缓冲区,按ESC-x去除制表符(untabify).) 调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告(warnings). 使用-tt时警告(warnings)将变成错误(errors).这些选项是被高度推荐的. 对于新的项目,强烈推荐仅使用空格(spaces-only)而不是制表符. 许多编辑器拥有使之易于实现的功能.(在Emacs中,确认indent-tabs-mode是nil).

行的最大长度

(Maximum Line Length)

• 周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符 使将多个窗口并排放置成为可能.在这些设备上使用默认的折叠(wrapping)方式看起来有点丑陋. 因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符), 对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符. 折叠长行的首选方法是使用Pyhon支持的圆括号,方括号(brackets)和花括号(braces)内的行延续. 如果需要,你可以在表达式周围增加一对额外的圆括号, 但是有时使用反斜杠看起来更好.确认恰当得缩进了延续的行. Emacs的Python-mode正确得完成了这些.一些例子:

   1         class Rectangle(Blob):
   2 
   3                 def __init__(self, width, height,
   4                                          color='black', emphasis=None, highlight=0):
   5                         if width == 0 and height == 0 and \
   6                            color == 'red' and emphasis == 'strong' or \
   7                            highlight > 100:
   8                                 raise ValueError, "sorry, you lose"
   9                         if width == 0 and height == 0 and (color == 'red' or
  10                                                                                            emphasis is None):
  11                                 raise ValueError, "I don't think so"
  12                         Blob.__init__(self, width, height,
  13                                                   color, emphasis, highlight)

空行

(Blank Lines)

• 用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割. 额外的空行可被用于(保守的(sparingly))分割相关函数组成的群(groups of related functions). 在一组相关的单句中间可以省略空行.(例如.一组哑元(a set of dummy implementations)). 当空行用于分割方法(method)的定义时,在'class'行和第一个方法定义之间也要有一个空行. 在函数中使用空行时,请谨慎的用于表示一个逻辑段落(indicate logical sections). Python接受contol-L(即^L)换页符作为空格;Emacs(和一些打印工具) 视这个字符为页面分割符,因此在你的文件中,可以用他们来为相关片段(sections)分页.

编码

(Encodings)[wiki:epes/pep-0263.html (PEP 263)]

• Python核心发布中的代码必须始终使用ASCII或Latin-1编码(又名 ISO-8859-1). 使用ASCII的文件不必有译码cookie(coding cookie). Latin-1仅当注释或文档字符串涉及作者名字需要Latin-1时才被使用; 另外使用\x转义字符是在字符串中包含非ASCII(non-ASCII)数据的首选方法. 作为PEP 263实现代码的测试套件的部分文件是个例外.

{{{Python 2.4 以后内核支持 Unicode 了！ 不论什么情况使用 UTF-8 吧！这是王道！ }}}--ZoomQuiet

导入

(Imports)

• 通常应该在单独的行中导入(Imports),例如:

                No:  import sys, os
                Yes: import sys
                         import os

• 但是这样也是可以的:

                from types import StringType, ListType

• Imports 通常被放置在文件的顶部,仅在模块注释和文档字符串之后,在模块的全局变量和常量之前.Imports应该有顺序地成组安放.
  1. 标准库的导入(Imports )
  2. 相关的主包(major package)的导入(即,所有的email包在随后导入)
  3. 特定应用的导入(imports)
• 你应该在每组导入之间放置一个空行.
• 对于内部包的导入是不推荐使用相对导入的.对所有导入都要使用包的绝对路径.
• 从一个包含类的模块中导入类时,通常可以写成这样:

                from MyClass import MyClass
                from foo.bar.YourClass import YourClass

• 如果这样写导致了本地名字冲突,那么就这样写

                import MyClass
           import foo.bar.YourClass

• 即使用"MyClass.MyClass"和"foo.bar.YourClass.YourClass"

空格

(Whitespace in Expressions and Statements)

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

• "spam( ham[ 1 ], { eggs: 2 } )".  Always write this as "spam(ham[1], {eggs: 2})".

  • 紧挨着圆括号,方括号和花括号的,如:"spam( ham[ 1 ], { eggs: 2 } )".

  要始终将它写成"spam(ham[1], {eggs: 2})".

  "if x == 4 : print x , y ; x , y = y , x". Always write this as "if x == 4: print x, y; x, y = y, x".

  • 紧贴在逗号,分号或冒号前的,如:

  "if x == 4 : print x , y ; x , y = y , x". 要始终将它写成 "if x == 4: print x, y; x, y = y, x".

  • 紧贴着函数调用的参数列表前开式括号(open parenthesis )的,如"spam (1)".要始终将它写成"spam(1)".

  slicing, as in: "dict ['key'] = list [index]". Always write this as "dict['key'] = list[index]".

  • 紧贴在索引或切片(slicing?下标?)开始的开式括号前的,如:

  "dict ['key'] = list [index]".要始终将它写成"dict['key'] = list[index]".

  • 在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格,如:

   1                   x             = 1
   2                   y             = 2
   3                   long_variable = 3

• 要始终将它写成

   1                  x = 1
   2                  y = 2
   3                  long_variable = 3

• (不要对以上任意一条和他争论 --- Guido 养成这样的风格超过20年了.)

其它建议

(Other Recommendations)

• 始终在这些二元运算符两边放置一个空格:赋值(=), 比较(==, <, >, !=, <>, <=,>=, in, not in, is, is not), 布尔运算 (and, or, not).

* 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致.

• 一些例子:

   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)

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

   1                   def complex(real, imag=0.0):
   2                           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()

注释

(Comments)

• 同代码不一致的注释比没注释更差.当代码修改时,始终优先更新注释! 注释应该是完整的句子. 如果注释是一个短语或句子,首字母应该大写, 除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写). 如果注释很短,最好省略末尾的句号(period?结尾句末的停顿?也可以是逗号吧,) 注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾. 你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致 (译按:应该说是使这两种功能正常工作,". "给出了文档结构的提示). 用英语书写时,断词和空格是可用的. 非英语国家的Python程序员:请用英语书写你的注释,除非你120%的确信 这些代码不会被不懂你的语言的人阅读.

{{{我就是坚持全部使用中文来注释，真正要发布脚本工具时，再想E文的； 开发时每一瞬间都要用在思量中，坚决不用在E文语法，单词的回忆中！ }}}-- ZoomQUiet

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

注释块

(Block Comments)

• 注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次. 注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本). 注释块内的段落以仅含单个'#'的行分割. 注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释).

行内注释

(Inline Comments)

• (inline?内联?翻成"行内"比较好吧)
  • 一个行内注释是和语句在同一行的注释.行内注释应该谨慎适用. 行内注释应该至少用两个空格和语句分开. 它们应该以'#'和单个空格开始.

                x = x+1                 # Increment x

• 如果语意是很明了的,那么行内注释是不必要的,事实上是应该被去掉的. 不要这样写:

                x = x+1                 # Increment x

                x = x+1                 # Compensate for border

• 但是有时,这样是有益的:

                x = x+1                 # Compensate for border

文档化

(Documentation Strings)

• Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in [wiki:epes/pep-0257.htm PEP 257]. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译)

{{{Documentation Strings-- 文档化字符 ; 为配合 pydoc;epydoc,Doxygen等等文档化工具的使用,类似于MoinMoin 语法,约定一些字符, 以便自动提取转化为有意义的文档章节等等文章元素! -- Zoomq}}}

• 为所有公共模块,函数,类和方法编写文档字符串.文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释.这个注释应该在"def"这行后.
• [wiki:epes/pep-0257.htm PEP 257] 描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的""" 应该单独成行,例如:

          """Return a foobang

          Optional plotz says to frobnicate the bizbaz first.
          """

• 对单行的文档字符串,结尾的"""在同一行也可以.

{{{实际上Python 自个儿就使用文档化编码维护着所有内置对象的使用说明\ 不信的话常试:

• #python

>>> import time >>> 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) Help on built-in function time in module time:

time(...)

• time() -> floating point number Return the current time in seconds since the Epoch. Fractions of a second may be present if the system clock provides them.

}}}

版本注记

(Version Bookkeeping) (我觉得叫"注记"更好)

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

   1                 __version__ = "$Revision: 1.4 $"
   2                 # $Source: E:/cvsroot/python_doc/pep8.txt,v $

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