Python开发编码规范

• --- hoxide 初译 dreamingk 校对发布 040724 --- xyb 重新排版 040915

Python开发编码规范

用Python进行开发时的编码风格约定

介绍(Introduction)

• This document gives coding conventions for the Python code comprising the standard library for the main Python describing style guidelines for the C code in the C implementation of Python[1]. 这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python 代码.请查阅相关的关于在Python的C实现中C代码风格指南的描述. This document was adapted from Guido's original Python Style Guide essay[2], with some additions from Barry's style guide[5]. Where there's conflict, Guido's style rules for the purposes of this PEP. This PEP may still be incomplete (in fact, it may never

  be finished <wink>). 这篇文档改编自Guido最初的《Python风格指南》一文. 并从《Barry's style guide》[5]中添加了部分内容. 在有冲突的地方，Guide的风格规则应该是符合本PEP的意图 (译注：就是当有冲突时，应以Guido风格为准) 这篇PEP也许仍然尚未完成(实际上，它可能永远不会结束).

愚蠢得使用一致性是无知的妖怪(A Foolish Consistency is the Hobgoblin of Little Minds)

{{{呆板的坚持一致性是傻的没边了! -- Zoomq}}}

• A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. 在这篇风格指导中的一致性是重要的. 在一个项目内的一致性更重要. 在一个模块或函数内的一致性最重要. But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgement. Look at other examples and decide what looks best. And don't hesitate to ask! 但最重要的是:知道何时会不一致 -- 有时只是没有实施风格指导.当出现疑惑时,
  • 运用你的最佳判断.看看别的例子,然后决定怎样看起来更好.并且要不耻下问!
  Two good reasons to break a particular rule: 打破一条既定规则的两个好理由: (1) When applying the rule would make the code less readable, even
  • for someone who is used to reading code that follows the rules.
  (1) 当应用这个规则是将导致代码可读性下降,即便对某人来说,他已经习惯于按这条规则来阅读代码了. (2) To be consistent with surrounding code that also breaks it
  • (maybe for historic reasons) -- although this is also an opportunity to clean up someone else's mess (in true XP style).
  (2) 为了和周围的代码保持一致而打破规则(也许是历史原因)
  • --- 虽然这也是个清除其它混乱的好机会(真正的XP风格).

代码的布局(Code lay-out)

缩进(Indentation)

• Use the default of Emacs' Python-mode: 4 spaces for one indentation level. For really old code that you don't want to mess up, you can continue to use 8-space tabs. Emacs Python-mode auto-detects the prevailing indentation level used in a file and sets its indentation parameters accordingly. 使用Emacs的Python-mode的默认值:4个空格一个缩进层次. 对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-space tabs). Emacs Python-mode自动发现文件中主要的缩进层次,依此设定缩进参数.

制表符还是空格(Tabs or Spaces)?

• Never mix tabs and spaces. The most popular way of indenting Python is with spaces only. The second-most popular way is with tabs only. Code indented with a mixture of tabs and spaces should be converted to using spaces exclusively. (In Emacs, select the whole buffer and hit ESC-x untabify.) When invoking the python command line interpreter with the -t option, it issues warnings about code that illegally mixes tabs and spaces. When using -tt these warnings become errors. These options are highly recommended! 永远不要混用制表符和空格. 最流行的Python缩进方式是仅使用空格, 其次是仅使用制表符.混合着制表符和空格缩进的代码将被转换成仅使用空格. (在Emacs中,选中整个缓冲区,按ESC-x去除制表符(untabify).) 调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告(warnings). 使用-tt时警告(warnings)将变成错误(errors).这些选项是被高度推荐的. For new projects, spaces-only are strongly recommended over tabs. Most editors have features that make this easy to do. (In Emacs, make sure indent-tabs-mode is nil). 对于新的项目,强烈推荐仅使用空格(spaces-only)而不是制表符. 许多编辑器拥有使之易于实现的功能.(在Emacs中,确认indent-tabs-mode是nil).

行的最大长度(Maximum Line Length)

• There are still many devices around that are limited to 80 character lines; plus, limiting windows to 80 characters makes it possible to have several windows side-by-side. The default wrapping on such devices looks ugly. Therefore, please limit all lines to a maximum of 79 characters (Emacs wraps lines that are exactly 80 characters long). For flowing long blocks of text (docstrings or comments), limiting the length to 72 characters is recommended. 周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符 使将多个窗口并排放置成为可能.在这些设备上使用默认的折叠(wrapping)方式看起来有点丑陋. 因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符), 对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符. The preferred way of wrapping long lines is by using Python's implied line continuation inside parentheses, brackets and braces. If necessary, you can add an extra pair of parentheses around an expression, but sometimes using a backslash looks better. Make sure to indent the continued line appropriately. Emacs Python-mode does this right. Some examples: 折叠长行的首选方法是使用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 \
               color == 'red' and emphasis == 'strong' or \
               highlight > 100:
   6                 raise ValueError, "sorry, you lose"
   7             if width == 0 and height == 0 and (color == 'red' or
   8                                                emphasis is None):
   9                 raise ValueError, "I don't think so"
  10             Blob.__init__(self, width, height,
  11                           color, emphasis, highlight)

空行(Blank Lines)

• Separate top-level function and class definitions with two blank lines. Method definitions inside a class are separated by a single blank line. Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between a bunch of related one-liners (e.g. a set of dummy implementations). 用两行空行分割顶层函数和类的定义,类内方法的定义用单个空行分割. 额外的空行可被用于(保守的(sparingly))分割相关函数组成的群(groups of related functions). 在一组相关的单句中间可以省略空行.(例如.一组哑元(a set of dummy implementations)). When blank lines are used to separate method definitions, there is also a blank line between the 'class' line and the first method definition. 当空行用于分割方法(method)的定义时,在'class'行和第一个方法定义之间也要有一个空行. Use blank lines in functions, sparingly, to indicate logical sections. 在函数中使用空行时,请谨慎的用于表示一个逻辑段落(indicate logical sections). Python accepts the control-L (i.e. ^L) form feed character as whitespace; Emacs (and some printing tools) treat these characters as page separators, so you may use them to separate pages of related sections of your file. Python接受contol-L(即^L)换页符作为空格;Emacs(和一些打印工具) 视这个字符为页面分割符,因此在你的文件中,可以用他们来为相关片段(sections)分页.

编码(Encodings)(PEP 263)

• Code in the core Python distribution should aways use the ASCII or Latin-1 encoding (a.k.a. ISO-8859-1). Files using ASCII should not have a coding cookie. Latin-1 should only be used when a comment or docstring needs to mention an author name that requires Latin-1; otherwise, using \x escapes is the preferred way to include non-ASCII data in string literals. An exception is made for those files that are part of the test suite for the code implementing PEP 263. Python核心发布中的代码必须始终使用ASCII或Latin-1编码(又名 ISO-8859-1). 使用ASCII的文件不必有译码cookie(coding cookie). Latin-1仅当注释或文档字符串涉及作者名字需要Latin-1时才被使用; 另外使用\x转义字符是在字符串中包含非ASCII(non-ASCII)数据的首选方法. 作为PEP 263实现代码的测试套件的部分文件是个例外.

导入(Imports)

• Imports should usually be on separate lines, e.g.:
• 通常应该在单独的行中导入(Imports),例如:

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

• it's okay to say this though: 但是这样也是可以的:

        from types import StringType, ListType

• Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants. Imports should be grouped, with the order being
• Imports 通常被放置在文件的顶部,仅在模块注释和文档字符串之后, 在模块的全局变量和常量之前.Imports应该有顺序地成组安放.
  1. standard library Imports
  2. related major package imports (i.e. all email package imports next)
  3. application specific imports
  4. 标准库的导入(Imports )
  5. 相关的主包(major package)的导入(即,所有的email包在随后导入)
  6. 特定应用的导入(imports) You should put a blank line between each group of imports. 你应该在每组导入之间放置一个空行.
• Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports.
• 对于内部包的导入是不推荐使用相对导入的.对所有导入都要使用包的绝对路径.
• When importing a class from a class-containing module, it's usually okay to spell this
• 从一个包含类的模块中导入类时,通常可以写成这样:

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

• If this spelling causes local name clashes, then spell them 如果这样写导致了本地名字冲突,那么就这样写

        import MyClass
       import foo.bar.YourClass

• and use "MyClass.MyClass" and "foo.bar.YourClass.YourClass"

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

表达式和语句中的空格(Whitespace in Expressions and Statements)

• Pet Peeves
  • Guido hates whitespace in the following places: Guido不喜欢在以下地方出现空格:
  • Immediately inside parentheses, brackets or braces, as in:

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

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

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

  • Immediately before a comma, semicolon, or colon, as in:

  "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".

  • Immediately before the open parenthesis that starts the argument

  list of a function call, as in "spam (1)". Always write this as "spam(1)".

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

  • Immediately before the open parenthesis that starts an indexing or

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

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

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

  • More than one space around an assignment (or other) operator to align it with another, as in:
  • 在赋值(或其它)运算符周围的用于和其它并排的一个以上的空格,如:

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

• Always write this as 要始终将它写成

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

• (Don't bother to argue with him on any of the above -- Guido's grown accustomed to this style over 20 years.) (不要对以上任意一条和他争论 --- Guido 养成这样的风格超过20年了.)

其它建议(Other Recommendations)

• Always surround these binary operators with a single space on

  either side: assignment (=), comparisons (==, <, >, !=, <>, <=, >=, in, not in, is, is not), Booleans (and, or, not).

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

• Use your better judgment for the insertion of spaces around arithmetic operators. Always be consistent about whitespace on either side of a binary operator. Some examples:
• 按你的看法在算术运算符周围插入空格. 始终保持二元运算符两边空格的一致. 一些例子:

   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)

• Don't use spaces around the '=' sign when used to indicate a keyword argument or a default parameter value. For instance:
• 不要在用于指定关键字参数或默认参数值的'='号周围使用空格,例如:

   1           def complex(real, imag=0.0):
   2               return magic(r=real, i=imag)

• Compound statements (multiple statements on the same line) are generally discouraged.
• 不要将多条语句写在同一行上.

          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)

• Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes! 同代码不一致的注释比没注释更差.当代码修改时,始终优先更新注释! Comments should be complete sentences. If a comment is a phrase or sentence, its first word should be capitalized, unless it is an identifier that begins with a lower case letter (never alter the case of identifiers!). 注释应该是完整的句子. 如果注释是一个短语或句子,首字母应该大写, 除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写). If a comment is short, the period at the end is best omitted. Block comments generally consist of one or more paragraphs built out of complete sentences, and each sentence should end in a period. 如果注释很短,最好省略末尾的句号(period?结尾句末的停顿?也可以是逗号吧,) 注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾. You should use two spaces after a sentence-ending period, since it makes Emacs wrapping and filling work consistenty. 你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致 (译按:应该说是使这两种功能正常工作,". "给出了文档结构的提示). When writing English, Strunk and White apply. 用英语书写时,断词和空格是可用的. Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don't speak your language. 非英语国家的Python程序员:请用英语书写你的注释,除非你120%的确信 这些代码不会被不懂你的语言的人阅读.

注释块(Block Comments)

• Block comments generally apply to some (or all) code that follows them, and are indented to the same level as that code. Each line of a block comment starts with a # and a single space (unless it is indented text inside the comment). Paragraphs inside a block comment are separated by a line containing a single #. Block comments are best surrounded by a blank line above and below them (or two lines above and a single line below for a block comment at the start of a a new section of function definitions). 注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次. 注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本). 注释块内的段落以仅含单个'#'的行分割. 注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释).

行内注释(Inline Comments)

• (inline?内联?翻成"行内"比较好吧)
  • An inline comment is a comment on the same line as a statement. Inline comments should be used sparingly. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space. 一个行内注释是和语句在同一行的注释.行内注释应该谨慎适用. 行内注释应该至少用两个空格和语句分开. 它们应该以'#'和单个空格开始. Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

        x = x+1                 # Increment x

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

        x = x+1                 # Increment x

• But sometimes, this is useful:

        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 PEP 257 [3]. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译)PEP 257 [3].

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

• Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line.
• 为所有公共模块,函数,类和方法编写文档字符串. 文档字符串对非公开的方法不是必要的,但你应该有一个描述这个方法做什么的注释. 这个注释应该在"def"这行后.
• PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, e.g.:
• PEP 257 描述了好的文档字符串的约定.一定注意,多行文档字符串结尾的""" 应该单独成行,例如:

      """Return a foobang

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

• For one liner docstrings, it's okay to keep the closing """ on the same line.
• 对单行的文档字符串,结尾的"""在同一行也可以.

版本注记(Version Bookkeeping)

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

• If you have to have RCS or CVS crud in your source file, do it as follows. 如果你要将RCS或CVS的杂项(crud)包含在你的源文件中,按如下做.

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

• These lines should be included after the module's docstring, before any other code, separated by a blank line above and below. 这个行应该包含在模块的文档字符串之后,所有代码之前,上下用一个空行分割.