Python开发编码规范

-- dreamingk [2004-08-09 01:10:29]

1. Python开发编码规范

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

1.1. 介绍(Introduction)

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

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

1.3. 代码的布局(Code lay-out)

1.3.1. 缩进(Indentation)

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

1.3.3. 行的最大长度(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 \
               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)

1.3.4. 空行(Blank Lines)

1.3.5. 编码(Encodings)(PEP 263)

1.4. 导入(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

1.5. 表达式和语句中的空格(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

1.5.1. 其它建议(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()

1.6. 注释(Comments)

1.6.1. 注释块(Block Comments)

1.6.2. 行内注释(Inline Comments)

        x = x+1                 # Increment x

        x = x+1                 # Increment x

        x = x+1                 # Compensate for border

        x = x+1                 # Compensate for border

1.7. 文档字符串(Documentation Strings)

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

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

1.8. 版本注记(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

1.9. 命名约定(Naming Conventions)

1.9.1. 描述:命名风格(Descriptive: Naming Styles)

1.9.2. 说明:命名约定(Prescriptive: Naming Conventions)

1.9.2.1. 应避免的名字(Names to Avoid)
1.9.2.2. 模块名(Module Names)
1.9.2.3. 类名(Class Names)
1.9.2.4. 异常名(Exception Names)
1.9.2.5. 全局变量名(Global Variable Names)
1.9.2.6. 函数名(Function Names)
1.9.2.7. 方法名和实例变量(Method Names and Instance Variables)
1.9.2.8. 继承的设计(Designing for inheritance)

1.10. 设计建议(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 \
           isinstance(obj, UnicodeType) :

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

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

last edited 2004-09-15 02:37:25 by 221