译稿 Python开发编码规范

TableOfContents

Python开发编码规范

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

用Python进行开发时的编码风格约定 原文:[wiki:epes/pep-0008.html PEP 008]《Style Guide for Python Code》

介绍

一致性的建议

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

代码的布局

(Code lay-out)

缩进

(Indentation)

制表符还是空格?

(Tabs or Spaces)

行的最大长度

(Maximum Line Length) 

   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)

编码

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

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

导入

(Imports) 

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

                from types import StringType, ListType

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

                import MyClass
           import foo.bar.YourClass

空格

(Whitespace in Expressions and Statements) 

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


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

其它建议

(Other Recommendations)

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

   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)

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

注释块

(Block Comments)

行内注释

(Inline Comments) 

                x = x+1                 # Increment x

                x = x+1                 # Increment x

                x = x+1                 # Compensate for border

                x = x+1                 # Compensate for border

文档化

(Documentation Strings)

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

          """Return a foobang

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

{{{实际上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(...)

}}}

版本注记

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

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