ChinesePython Wiki   Python码书写规格 UserPreferences
 
 ChinesePython Wiki   中蟒大杂院   最近修改   标题目录   文字目录   站内导航   求助 

'还没全部译好'

 
PEP: 8 
Title: Style Guide for Python Code 
Version: $Revision: 1.20 $ 
Author: guido@python.org (Guido van Rossum), 
    barry@python.org (Barry Warsaw) 
Status: Active 
Type: Informational 
Created: 05-Jul-2001 
Post-History: 05-Jul-2001 
 
Python 改良提案: 8 
标题: Python 码的书写规格 
版本: $Revision: 1.20$ 
作者: guido@python.org (Guide van Rossum), 
      barry@python.org (Barry Warsaw) 
状态: 作用中 
种类: 资讯 
建立: 2001年7月5日 
提交记录: 2001年7月5日 
 

 
Introduction 
简介 
 
    This document gives coding conventions for the Python code 
    comprising the standard library for the main Python distribution. 
    Please see the companion informational PEP describing style 
    guidelines for the C code in the C implementation of Python[1]. 
 
    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>). 
 
    本档旨在定立书写 Python 程式的一般格式. 此格式规范了 Python  
    标准库中的编码风格. 至于以 C 实现 Python 中 C 语言的书写规格,  
    有一篇和本文互补的 PEP 可供参考[1]. 
 
    本文基本内容来自 Guido 原来的一篇讲说 Python 风格的文献 [2], 并加 
    入了 Barry 所写的指引中部份内容. 当两篇参考档有不一致时, 本文以 
    Guido 的意见为标准. 这篇 PEP 尚未正式完成 (事实上, 它根本不可能 
    真正完工 ;) 
 
 
A Foolish Consistency is the Hobgoblin of Little Minds 
坚持愚蠢的一致是依附在脑子不健全者的恶鬼 (译按: 即不要官僚) 
 
    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. 
 
    (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). 
 
    书写规格所想达致的就是一致性。一致性对于本文很重要。一致性对于一个 
    专案来也是重要的。而任一模组或是函数其本身的一致性更有极严格的要求。 
 
    然而在这之上还有更重要的事∶要知道在适当时候保持不一致。在某些场合 
    本文所要求的规格并不适用。如果遇到问题,请自行做出合理判断。参考其 
    他人的做法来帮你决定怎样看起来才最好。不要怕发问! 
 
    以下有两个好的理由支持你舍弃某条规定∶ 
 
    (1) 当套用了规定的方式来书写程式会使程式码变得不清晰, 而且其不清晰 
        的程度就算惯看依从规格的程式的人也觉得不好. 
 
    (2) 如果要修改的段落其上文下理的编排都不服从该规格(或许是以前流传下 
        来的). -- 不过依照 eXtreme Programming 的理念, 这个正是把以前留 
        下的问题改过来的好机会. 
 
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. 
 
    请用 Emac 的 Python-mode 的预设格式: 4 个空白格代表一层缩排. 如果 
    还到一些真的很旧的程式,为避免把它弄糟可以保留用代表 8 个空格的跳格 
    符 (Tab). 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! 
 
    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). 
 
    绝对不要夹杂地使用跳格和空格来做缩进. Python 程式中最多使用的缩进 
    方式是只用空格来做缩排. 第二常用的是只用跳格. 如果程式码中混合使 
    用空格及跳和的话,请把全部跳格转换成空格. (在 Emcas 中, 选取全部内容 
    然后按 ECS-x untabify.) 当你以 -t 选项来启动 Python 后, 它会就程式中 
    混用空格和跳格的段落提出警告. 如果是 -tt 选项, 则这些警告会升级成为 
    错误而程式将无法运行. 请多利用这些选项. 
 
    新成立的专案应尽量采用纯空格的方式来缩排程式码. 大部份编辑工具中 
    都提供相关的设置. (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. 
 
    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: 
 
    目前仍然不少设备只充许一行最多 80 个字符; 而且如果限制每行 80 字符 
    的话可以把几个编程的窗口并排以便对照. 用设备预设的换行方式看上去很 
    恶心.为此,每一行应以不超过 79 个字符为佳 (Emacs 会在第 80 个格上 
    就换行). 当编排很长的一段文字时(比如说 docstring 或者注释), 每行 
    72 个字符就够了. 
 
    Python 在遇到行尾有未完的括号,方括号,花括号时会判断为该行尚末完成 
    而把下一行内容连在一块解析. 这个特性在人手替过长的程式换行时要好好 
    利用. 视不同情况,你可以用额外的括号把表达式包起来以达到想要的 
    换行结果;也可以只在行末加上反斜线来表示这一行还没写完. 
 
    class Rectangle(Blob): 
 
        def __init__(self, width, height, 
                     color='black', emphasis=None, highlight=0): 
            if width == 0 and height == 0 and \ 
               color == 'red' and emphasis == 'strong' or \ 
               highlight > 100: 
                raise ValueError, "sorry, you lose" 
            if width == 0 and height == 0 and (color == 'red' or 
                                               emphasis is None): 
                raise ValueError, "I don't think so" 
            Blob.__init__(self, width, height, 
                          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). 
 
    When blank lines are used to separate method definitions, there is 
    also a blank line between the `class' line and the first method 
    definition. 
 
    Use blank lines in functions, sparingly, to 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. 
 
    每一个最上层的函数以及定义类时要用两行空白行隔开. 定义类之中的方法 
    时要用一行空行作间隔. 有时候(不普遍)在一组相似的函数的前后可以加上 
    额外的空行. 然而有些函数内容非常简单而目的又接近的话,分隔行是可以 
    节省的 (比如一组 dummy implementations, 就是只做做样子但无实际功能 
    的函数) 
     
    如果定义类之中的方法时用了空行来分隔每个方法, 则第一个被定义的方法 
    和定义类本身的 "class" 这一行之间也要加一行空行. 
 
    函数定义中,每个逻辑段(如一组 if 或 for)之间可以选择性地加上空行. 
 
    Python 在解析程式时视分页符号 (就是 ^L) 等同于空白键; 而 Emacs  
    (及某些打印工具)则视它为另起新页. 因此你可以在程式档中适当地利用 
    它来编分不同的段落. 
     
 
  Encodings (PEP 263) 
  编码 (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 储存的档案不该加上编码识别暗号(coding cookie). 要用到  
    Latin-1 编码只有一种情况,就是在说明条或是注释行中提到的程式员的 
    名字中有 Latin-1 码;除此之外,在字串中的非 ASCII 字符最好用 \x 方式 
    表示. 有一类程式档不受此规范,就是那些用来测试 PEP 263 部份代码的程 
    式. 
 
Imports 
加载 
 
    - Imports should usually be on separate lines, e.g.: 
 
        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 
 
      1. standard library imports 
      2. related major package imports (i.e. all email package imports next) 
      3. application specific 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" 
 
    - 加载模组应分开每一个占一行, 象这样: 
 
        No:  import sys, os 
        Yes: import sys 
             import os 
 
      不过象下面这样则无所谓: 
 
        from types import StringType, ListType 
 
    - 加载模组的程式码永达要置于档案的最开头, 紧跟着注释及说明条(如果有的话), 
      并在宣告全局变量及常数之前. 加载的次序应如下: 
 
      1. 加载标准库中的模组 
      2. 相关的主要模组包 
      3. 加载程式专用的模组 
 
      每一组加载完后要加一空行以兹分隔. 
 
    - 尽管 Python 允许在同一个模组包内用相对的路径来指向要加载的模组,  
      这种做法并不受到鼓励. 所有的加载动作一定要指明绝对来源. 
 
    - 当载入模组包中的某一个类时,下面的写法也没问题: 
 
        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 
表达式或述句中的空格 
 
  Pet Peeves 
 
    Guido hates whitespace in the following places: 
 
    - Immediately inside parentheses, brackets or braces, as in: 
      "spam( ham[ 1 ], { eggs: 2 } )".  Always write this as 
      "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". 
 
    - Immediately before the open parenthesis that starts the argument 
      list of a function call, as in "spam (1)".  Always write 
      this as "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]". 
 
    - More than one space around an assignment (or other) operator to 
      align it with another, as in: 
 
          x             = 1 
          y             = 2 
          long_variable = 3 
 
      Always write this as 
 
          x = 1 
          y = 2 
          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.) 
 
  Pet Peeves 的说法 
 
    Guido 讨厌象下面那样放置空格符:    
 
    - 紧跟着括号后面来一个空格, 象 
      "spam( ham[ 1 ], { eggs: 2 } )". 要写成这样才行: 
      "spam(ham[1], {eggs: 2})". 
 
    - 在逗号前放置空格, 象 
      "if x == 4 : print x , y ; x , y = y , x".  要这样写才行: 
      "if x == 4: print x, y; x, y = y, x". 
 
    - 在调用函数的开括号前加上空格, 象 "spam (1)".  要写成 "spam(1)". 
 
 
    - 在引用索引或是片断的开括号前加上空格, 象 "dict ['key'] = list [index]". 
      要写成 "dict['key'] = list[index]" 才好. 
 
    - 在赋值 (或其他) 号的前后加入多于一个空格符, 象 
          x             = 1 
          y             = 2 
          long_variable = 3 
 
      要写成下面这样才行: 
 
          x = 1 
          y = 2 
          long_variable = 3 
 
     (请不要花时间跟 Guido 辩论上面的任何一条 -- 这些写法已跟着他成长了二十年以上.) 
 
  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). 
 
    - 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: 
 
          i = i+1 
          submitted = submitted + 1 
          x = x*2 - 1 
          hypot2 = x*x + y*y 
          c = (a+b) * (a-b) 
          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: 
 
          def complex(real, imag=0.0): 
              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() 
 
    - 下列操作符的前后一定要加上一个空格: 赋值 (=), 比较 (==, <, >, !=,  
      <>, <=, >=, in, not in, is, is not>, 直值 (and, or, not). 
 
    - 写作算术公式时请自行判断怎样才是适当的加入空格符. 对于二元操作符号 
      前后的空格一定要一致. 下面是一些例子: 
 
          i = i+1 
          submitted = submitted + 1 
          x = x*2 - 1 
          hypot2 = x*x + y*y 
          c = (a+b) * (a-b) 
          c = (a + b) * (a - b) 
 
    - 如果等于符号 (=) 是用在参数列来指定预设参数值时, 它的前后不要加上空格. 
      比如说: 
  
          def complex(real, imag=0.0): 
              return magic(r=real, i=imag) 
 
    - 最好不要写复式句 (在同一行内容纳多于一个述句). 
 
          好的:  if foo == 'blah': do_blah_thing() 
          不好: if foo == 'blah': 
                   do_blah_thing() 
 
          好的:  do_one(); do_two(); do_three() 
          不好: 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. 
 
    You should use two spaces after a sentence-ending period, since it 
    makes Emacs wrapping and filling work consistenty. 
 
    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. 
 
    和程式内容相左的注释比没有注释更讨厌. 当程式码在所改动时, 第一时 
    间更新有关的注释. 
 
    注释时要用完整的句子. 对英文写的注释, 除非第一个字是变数名称或是保留字,  
    否则句首第一个字母要用大写. (永远不要改动变数名的大小写法) 
 
    如果注释很短的话, 最后的句号最好省掉. 区块式的注释应包含一个或更多以 
    完整句子组成的段落, 每个句子最后要加上句号. 
 
    英文注释下, 句子完结后应加上两个空格, 这样的话 Emacs 的换行和靠齐的操作 
    能保持一致. 
 
    书写英文时, 请应用 Strunk 和 White 书中的规则. 
 
    非英语国家的 Python 编程人员: 请用英文来写注释. 除非你百分之一百二十 
    肯定你的程式不会被其他不懂你的语言的人阅读. 
  
 
  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 
  行内注释 
 
    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 
 
    But sometimes, this is useful: 
 
        x = x+1                 # Compensate for border 
 
    行内注释的形式是在述句的同一行中加注释. 行内注释不应用的过多. 注释 
    文字要和述句本身分开起码两个空格符. 它们应以 # 和一个空格作为开始. 
 
    行内注释的内容不要描述显而易见的事, 如此只会造成滋扰. 不要做这样的事: 
 
        x = x+1                 # Increment x 
 
    下面是一个好的例子: 
 
        x = x+1                 # Compensate for border 
 
 
Documentation Strings 
说明字串 
 
    Conventions for writing good documentation strings 
    (a.k.a. "docstrings") are immortalized in PEP 257 [3]. 
 
    - 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. 
 
    - 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.: 
 
      """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. 
 
    关于如何书写良好的说明字串 ('docstring') 的问题已经在 PEP 257 [3]  
    中提及. 
 
    - 所有公开的模组, 函数, 类别, 及方法都要有相关的说明字串. 说明字串 
      并不必出现在非公开的方法中. 不过你应该写下一些注释, 说明该方法是 
      干什么用的, 此注释应置于 'def' 这行之下. 
 
    - PEP 257 记录了写好说明字串的一些约定. 注意其中最重要的一项是在当 
      说明字串多于一行时, 末尾的 """ 要自成一行. 象这样: 
 
      """Return a foobang 
 
      Optional plotz says to frobnicate the bizbaz first. 
      """ 
 
    - 对于只有一行的说明字串, 把 """ 放到同一行也没问题. 
 
Version Bookkeeping 
版本记录 
 
    If you have to have RCS or CVS crud in your source file, do it as 
    follows. 
 
        __version__ = "$Revision: 1.20 $" 
        # $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $ 
 
    These lines should be included after the module's docstring, 
    before any other code, separated by a blank line above and 
    below. 
 
    如果你程式码中有用 RCS 或 CVS, 用下面的方法: 
 
        __version__ = "$Revision: 1.20 $" 
        # $Source: /cvsroot/python/python/nondist/peps/pep-0008.txt,v $ 
 
    上面这几行要跟在模块的说明文字之后, 在正式的程式码之前, 并且在前后 
    都加上一行空行.  
 
Naming Conventions 
 
    The naming conventions of Python's library are a bit of a mess, so 
    we'll never get this completely consistent -- nevertheless, here 
    are some guidelines. 
 
  Descriptive: Naming Styles 
 
    There are a lot of different naming styles.  It helps to be able 
    to recognize what naming style is being used, independently from 
    what they are used for. 
 
    The following naming styles are commonly distinguished: 
 
    - x (single lowercase letter) 
 
    - X (single uppercase letter) 
 
    - lowercase 
 
    - lower_case_with_underscores 
 
    - UPPERCASE 
 
    - UPPER_CASE_WITH_UNDERSCORES 
 
    - CapitalizedWords (or CapWords, or CamelCase -- so named because 
      of the bumpy look of its letters[4]) 
 
    - mixedCase (differs from CapitalizedWords by initial lowercase 
      character!) 
 
    - Capitalized_Words_With_Underscores (ugly!) 
 
    There's also the style of using a short unique prefix to group 
    related names together.  This is not used much in Python, but it 
    is mentioned for completeness.  For example, the os.stat() 
    function returns a tuple whose items traditionally have names like 
    st_mode, st_size, st_mtime and so on.  The X11 library uses a 
    leading X for all its public functions.  (In Python, this style is 
    generally deemed unnecessary because attribute and method names 
    are prefixed with an object, and function names are prefixed with 
    a module name.) 
 
    In addition, the following special forms using leading or trailing 
    underscores are recognized (these can generally be combined with any 
    case convention): 
 
    - _single_leading_underscore: weak "internal use" indicator 
      (e.g. "from M import *" does not import objects whose name 
      starts with an underscore). 
 
    - single_trailing_underscore_: used by convention to avoid 
      conflicts with Python keyword, e.g. 
      "Tkinter.Toplevel(master, class_='ClassName')". 
 
    - __double_leading_underscore: class-private names as of Python 1.4. 
 
    - __double_leading_and_trailing_underscore__: "magic" objects or 
      attributes that live in user-controlled namespaces, 
      e.g. __init__, __import__ or __file__.  Sometimes these are 
      defined by the user to trigger certain magic behavior 
      (e.g. operator overloading); sometimes these are inserted by the 
      infrastructure for its own use or for debugging purposes.  Since 
      the infrastructure (loosely defined as the Python interpreter 
      and the standard library) may decide to grow its list of magic 
      attributes in future versions, user code should generally 
      refrain from using this convention for its own use.  User code 
      that aspires to become part of the infrastructure could combine 
      this with a short prefix inside the underscores, 
      e.g. __bobo_magic_attr__. 
 
  Prescriptive: Naming Conventions 
 
    Names to Avoid 
 
      Never use the characters `l' (lowercase letter el), `O' 
      (uppercase letter oh), or `I' (uppercase letter eye) as single 
      character variable names.  In some fonts, these characters are 
      indistinguisable from the numerals one and zero.  When tempted 
      to use `l' use `L' instead. 
 
    Module Names 
 
      Module names can be either CapWords or lowercase.  There is no 
      unambiguous convention to decide which to use.  Modules that 
      export a single class (or a number of closely related classes, 
      plus some additional support) are often named in CapWords, with 
      the module name being the same as the class name (e.g. the 
      standard StringIO module).  Modules that export a bunch of 
      functions are usually named in all lowercase. 
 
      Since module names are mapped to file names, and some file 
      systems are case insensitive and truncate long names, it is 
      important that module names be chosen to be fairly short and not 
      in conflict with other module names that only differ in the case 
      -- this won't be a problem on Unix, but it may be a problem when 
      the code is transported to Mac or Windows. 
 
      There is an emerging convention that when an extension module 
      written in C or C++ has an accompanying Python module that 
      provides a higher level (e.g. more object oriented) interface, 
      the Python module's name CapWords, while the C/C++ module is 
      named in all lowercase and has a leading underscore 
      (e.g. _socket). 
 
      Python packages generally have a short all lowercase name. 
 
    Class Names 
 
      Almost without exception, class names use the CapWords 
      convention.  Classes for internal use have a leading underscore 
      in addition. 
 
    Exception Names 
 
      If a module defines a single exception raised for all sorts of 
      conditions, it is generally called "error" or "Error".  It seems 
      that built-in (extension) modules use "error" (e.g. os.error), 
      while Python modules generally use "Error" (e.g. xdrlib.Error). 
      The trend seems to be toward CapWords exception names. 
 
    Function Names 
 
      Plain functions exported by a module can either use the CapWords 
      style or lowercase (or lower_case_with_underscores).  There is 
      no strong preference, but it seems that the CapWords style is 
      used for functions that provide major functionality 
      (e.g. nstools.WorldOpen()), while lowercase is used more for 
      "utility" functions (e.g. pathhack.kos_root()). 
 
    Global Variable Names 
 
      (Let's hope that these variables are meant for use inside one 
      module only.)  The conventions are about the same as those for 
      exported functions.  Modules that are designed for use via "from 
      M import *" should prefix their globals (and internal functions 
      and classes) with an underscore to prevent exporting them. 
 
    Method Names 
 
      The story is largely the same as for functions.  Use lowercase 
      for methods accessed by other classes or functions that are part 
      of the implementation of an object type.  Use one leading 
      underscore for "internal" methods and instance variables when 
      there is no chance of a conflict with subclass or superclass 
      attributes or when a subclass might actually need access to 
      them.  Use two leading underscores (class-private names, 
      enforced by Python 1.4) in those cases where it is important 
      that only the current class accesses an attribute.  (But realize 
      that Python contains enough loopholes so that an insistent user 
      could gain access nevertheless, e.g. via the __dict__ attribute.) 
 
    Designing for inheritance 
 
      Always decide whether a class's methods and instance variables 
      should be public or non-public.  In general, never make data 
      variables public unless you're implementing essentially a 
      record.  It's almost always preferrable to give a functional 
      interface to your class instead (and some Python 2.2 
      developments will make this much nicer). 
 
      Also decide whether your attributes should be private or not. 
      The difference between private and non-public is that the former 
      will never be useful for a derived class, while the latter might 
      be.  Yes, you should design your classes with inheritence in 
      mind! 
 
      Private attributes should have two leading underscores, no 
      trailing underscores. 
 
      Non-public attributes should have a single leading underscore, 
      no trailing underscores. 
 
      Public attributes should have no leading or trailing 
      underscores, unless they conflict with reserved words, in which 
      case, a single trailing underscore is preferrable to a leading 
      one, or a corrupted spelling, e.g. class_ rather than klass. 
      (This last point is a bit controversial; if you prefer klass 
      over class_ then just be consistent. :). 
 
 
Programming Recommendations 
编程建议 
 
    - Comparisons to singletons like None should always be done with 
      'is' or 'is not'.  Also, beware of writing "if x" when you 
      really mean "if x is not None" -- e.g. when testing whether a 
      variable or argument that defaults to None was set to some other 
      value.  The other value might be a value that's false in a 
      Boolean context! 
 
    - Class-based exceptions are always preferred over string-based 
      exceptions.  Modules or packages should define their own 
      domain-specific base exception class, which should be subclassed 
      from the built-in Exception class.  Always include a class 
      docstring.  E.g.: 
 
        class MessageError(Exception): 
            """Base class for errors in the email package.""" 
 
    - Use string methods instead of the string module unless 
      backward-compatibility with versions earlier than Python 2.0 is 
      important.  String methods are always much faster and share the 
      same API with unicode strings. 
 
    - Avoid slicing strings when checking for prefixes or suffixes. 
      Use startswith() and endswith() instead, since they are 
      cleaner and less error prone.  For example: 
 
        No:  if foo[:3] == 'bar': 
        Yes: if foo.startswith('bar'): 
 
      The exception is if your code must work with Python 1.5.2 (but 
      let's hope not!). 
 
    - Object type comparisons should always use isinstance() instead 
      of comparing types directly.  E.g. 
 
        No:  if type(obj) is type(1): 
        Yes: if isinstance(obj, int): 
 
      When checking if an object is a string, keep in mind that it 
      might be a unicode string too!  In Python 2.3, str and unicode 
      have a common base class, basestring, so you can do: 
 
        if isinstance(obj, basestring): 
 
      In Python 2.2, the types module has the StringTypes type defined 
      for that purpose, e.g.: 
 
        from types import StringTypes 
        if isinstance(obj, StringTypes): 
 
      In Python 2.0 and 2.1, you should do: 
 
        from types import StringType, UnicodeType 
        if isinstance(obj, StringType) or \ 
           isinstance(obj, UnicodeType) : 
 
    - For sequences, (strings, lists, tuples), use the fact that empty 
      sequences are false, so "if not seq" or "if seq" is preferable 
      to "if len(seq)" or "if not len(seq)". 
 
    - Don't write string literals that rely on significant trailing 
      whitespace.  Such trailing whitespace is visually 
      indistinguishable and some editors (or more recently, 
      reindent.py) will trim them. 
 
    - Don't compare boolean values to True or False using == (bool 
      types are new in Python 2.3): 
 
        No:  if greeting == True: 
        Yes: if greeting: 
 
    - 和单子 (Singlton, 即在程式中只有一个实体) 如 None 做比较时, 尽量 
      用 'is' 或 'is not'. 同时, 当你写 'if x' 时, 想清楚你是不是其实 
      是指 'if x is not None' -- 例如测试某个本来是 None 的变数或参数  
      有没有被成其他的值. 小心有些情况下变数被改动了, 但改动后的值在 
      布林真值测试下会传回'假', 如此一来用 'if x' 就会被骗了. 
 
    - 以类别为基础的异常定义和以字串为基础的异常定义两者间, 尽量用类 
      别式的. 模块或是套件应该在它们自己的应用范围内自行定义异常类. 这 
      些异常类应由基本异常类继承而来. 一定要加上一个类的说明字串. 如: 
 
        class MessageError(Exception): 
            """Base class for errors in the email package.""" 
 
    - 字串操作时尽量用字符串的方法代替字串模组, 除非必需要兼容 Python 2.0  
      以前的版本. 字串方法几乎总要快一些, 并且和统一码的字串使同相同的 
      介面. 
 
    - 如果是检查字串的前缀或是后缀时, 避免用取片断的方法. 用 startwith() 
      和 endswith() 比较直观和少些机会出错. 例如: 
 
 
        不好: if foo[:3] == 'bar': 
        好的: if foo.startswith('bar'): 
 
      但是如果你要写给 Python 1.5.2 的话则例外. (希望你不必.) 
 
 
    - 比较对象的类型时不要直接比较, 要用 isinstance(): 
 
        不好: if type(obj) is type(1): 
        好的: if isinstance(obj, int):     
 
      如果要测试一个对象是不是字串类, 留心统一码字串也是字串类的. 在 
      Python 2.3, str 和 unicode 共用同一个基底类, basestring, 因此可以 
      用 
 
        if isinstance(obj, basestring): 
 
      在 Python 2.2, type 模组中定义了一个 StringTypes 可用: 
 
        from types import StringTypes 
        if isinstance(obj, StringTypes): 
 
      在 Python 2.0 和 2.1, 你应该这样写: 
 
        from types import StringType, UnicodeType 
        if isinstance(obj, StringType) or \ 
           isinstance(obj, UnicodeType) : 
 
    - 对于序列类, (如字串, 列表, 元组), 根据空序列的布林真值为 '假',  
      用 'if not seq' 或 'if seq' 来判别空序列要比用 'if len(seq)' 及 
      'if not len(seq)' 更好. 
 
    - 创建字串时不要在末尾放过多的空格符, 它们在视觉上不容易分辨, 而且 
      在些编辑器(或者是最近的 reindent.py 和程式) 会把它们裁掉的. 
 
    - 比较真值时不要用 '==' 号来和 True, False 作比较 (bool 型是在 Python 
      2.3 新加的) 
 
        不好: if greeting == True: 
        好的: if greeting: 
 
 
References 
参考文献 
 
   [1] PEP 7, Style Guide for C Code, van Rossum 
 
    [2] http://www.python.org/doc/essays/styleguide.html 
 
    [3] PEP 257, Docstring Conventions, Goodger, van Rossum 
 
    [4] http://www.wikipedia.com/wiki/CamelCase 
 
    [5] Barry's GNU Mailman/mimelib style guide 
        http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mimelib/mimelib/STYLEGUIDE.txt?rev=1.1&content-type=text/vnd.viewcvs-markup 
 
 
Copyright 
 
    This document has been placed in the public domain. 
 
版权 
 
    此文件已宣告为公有. 
 
 
 
 
Local Variables: 
mode: indented-text 
indent-tabs-mode: nil 
End: 
 

PythonPowered
编辑文字 of 本页 (上次修改 2004-05-11 03:04:13)
查找页面 by browsing, title search , text search or an index
或尝试以下动作: LikePages, LocalSiteMap, SpellCheck