Python开发编码规范

{*} 文档化开发注释规范

Python Coding Rule

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

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

原文:PEP 008 《Style Guide for Python Code》

下载(中文pdf): PythonCodingRule.pdf

介绍

一致性的建议

愚蠢得使用一致性是无知的妖怪(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                 def __init__(self, width, height,
   3                              color='black', emphasis=None, highlight=0):
   4                         if width == 0 and height == 0 and \
   5                            color == 'red' and emphasis == 'strong' or \
   6                            highlight > 100:
   7                                 raise ValueError, "sorry, you lose"
   8                         if width == 0 and height == 0 and (color == 'red' or
   9                                                            emphasis is None):
  10                                 raise ValueError, "I don't think so"
  11                         Blob.__init__(self, width, height,
  12                                       color, emphasis, highlight)

空行

(Blank Lines)

编码

(Encodings)(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 自个儿就使用文档化编码维护着所有内置对象的使用说明\
不信的话常试:
        #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) (我觉得叫"注记"更好)

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

对于CVS的服务器工作标记更应该在代码段中明确出它的使用
如:在文档的最开始的版权声明后应加入如下版本标记:
# 文件:$id$
# 版本: $Revision$
这样的标记在提交给配置管理服务器后,会自动适配成为相应的字符串,如:
# 文件:$Id: ussp.py,v 1.22 2004/07/21 04:47:41 hd Exp $
# 版本: $Revision: 1.4 $
----HD

命名约定

(Naming Conventions)

描述:命名风格

(Descriptive: Naming Styles)

(在Python中,这个风格通常认为是不必要的, 因为属性和方法名以对象作前缀,而函数名以模块名作前缀.)

说明:命名约定

(Prescriptive: Naming Conventions)

应避免的名字

(Names to Avoid)

模块名

(Module Names)

类名

(Class Names)

异常名

(Exception Names)

全局变量名

(Global Variable Names)

函数名

(Function Names)

方法名和实例变量

(Method Names and Instance Variables)

继承的设计

(Designing for inheritance)

设计建议

(Programming Recommendations)

   1                 class MessageError(Exception):
   2                         """Base class for errors in the email package."""

                No:  if foo[:3] == 'bar':
                Yes: if foo.startswith('bar'):

                No:  if type(obj) is type(1):
                Yes: if isinstance(obj, int):

   1                 if isinstance(obj, basestring):

   1                 from types import StringTypes
   2                 if isinstance(obj, StringTypes):

   1                 from types import StringType, UnicodeType
   2                 if isinstance(obj, StringType) or \
   3                    isinstance(obj, UnicodeType) :

                No:  if greeting == True:
                Yes: if greeting:
                No:  if greeting == True:
                Yes: if greeting:


PythonCodingRule (last edited 2010-09-03 09:14:06 by ZoomQuiet)