Python Coding Rule

出自sebug security vulnerability(SSV) DB
跳转到: 导航, 搜索

目录

介绍

这篇文档所给出的编码约定适用于在主要的Python发布版本中组成标准库的Python 代码.请查阅相关的关于在Python的C实现中C代码风格指南的描述. 这篇文档改编自Guido最初的《Python风格指南》一文. 并从《Barry's style guide》中添加了部分内容. 在有冲突的地方,Guide的风格规则应该是符合本PEP的意图 (译注:就是当有冲突时,应以Guido风格为准) 这篇PEP也许仍然尚未完成(实际上,它可能永远不会结束).


一致性的建议

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

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

在这篇风格指导中的一致性是重要的. 在一个项目内的一致性更重要. 在一个模块或函数内的一致性最重要. 但最重要的是:知道何时会不一致 -- 有时只是没有实施风格指导.当出现疑惑时,运用你的最佳判断.看看别的例子,然后决定怎样看起来更好.并且要不耻下问!

  1. 当应用这个规则是将导致代码可读性下降,即便对某人来说,他已经习惯于按这条规则来阅读代码了.
  2. 为了和周围的代码保持一致而打破规则(也许是历史原因)
    1. 虽然这也是个清除其它混乱的好机会(真正的XP风格).


代码的布局

缩进

使用Emacs的Python-mode的默认值:4个空格一个缩进层次. 对于确实古老的代码,你不希望产生混乱,可以继续使用8空格的制表符(8-space tabs). Emacs Python-mode自动发现文件中主要的缩进层次,依此设定缩进参数.


制表符还是空格

永远不要混用制表符和空格. 最流行的Python缩进方式是仅使用空格, 其次是仅使用制表符.混合着制表符和空格缩进的代码将被转换成仅使用空格. (在Emacs中,选中整个缓冲区,按ESC-x去除制表符(untabify).) 调用python命令行解释器时使用-t选项,可对代码中不合法得混合制表符和空格发出警告(warnings). 使用-tt时警告(warnings)将变成错误(errors).这些选项是被高度推荐的. 对于新的项目,强烈推荐仅使用空格(spaces-only)而不是制表符. 许多编辑器拥有使之易于实现的功能.(在Emacs中,确认indent-tabs-mode是nil).


行的最大长度

周围仍然有许多设备被限制在每行80字符;而且,窗口限制在80个字符 使将多个窗口并排放置成为可能.在这些设备上使用默认的折叠(wrapping)方式看起来有点丑陋. 因此,请将所有行限制在最大79字符(Emacs准确得将行限制为长80字符), 对顺序排放的大块文本(文档字符串或注释),推荐将长度限制在72字符. 折叠长行的首选方法是使用Pyhon支持的圆括号,方括号(brackets)和花括号(braces)内的行延续. 如果需要,你可以在表达式周围增加一对额外的圆括号, 但是有时使用反斜杠看起来更好.确认恰当得缩进了延续的行. Emacs的Python-mode正确得完成了这些.一些例子:

  1. class Rectangle(Blob):
  2. 	def __init__(self, width, height,color='black', emphasis=None, highlight=0):
  3. 		if width == 0 and height == 0 and color == 'red' and emphasis == 'strong' or highlight > 100:
  4. 			raise ValueError, "sorry, you lose"
  5. 				if width == 0 and height == 0 and (color == 'red' or emphasis is None):
  6. 					raise ValueError, "I don't think so"
  7. 						Blob.__init__(self, width, height,color, emphasis, highlight)


空行


编码

Python核心发布中的代码必须始终使用ASCII或Latin-1编码(又名 ISO-8859-1). 使用ASCII的文件不必有译码cookie(coding cookie). Latin-1仅当注释或文档字符串涉及作者名字需要Latin-1时才被使用; 另外使用\x转义字符是在字符串中包含非ASCII(non-ASCII)数据的首选方法. 作为PEP 263实现代码的测试套件的部分文件是个例外.

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


导入

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

但是这样也是可以的:

from types import StringType, ListType
  1. 标准库的导入(Imports )
  2. 相关的主包(major package)的导入(即,所有的email包在随后导入)
  3. 特定应用的导入(imports)
from MyClass import MyClass
from foo.bar.YourClass import YourClass

如果这样写导致了本地名字冲突,那么就这样写

import MyClass
import foo.bar.YourClass

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


空格

Guido不喜欢在以下地方出现空格:

"spam( ham[ 1 ], { eggs: 2 } )".  Always write this as "spam(ham[1], {eggs: 2})".
"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".
slicing, as in: "dict ['key'] = list [index]". Always write this as "dict['key'] = list[index]".
"dict ['key'] = list [index]".要始终将它写成"dict['key'] = list[index]".
  1. x                          = 1
  2. y                          = 2
  3. long_variable  = 3

要始终将它写成

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

(不要对以上任意一条和他争论 --- Guido 养成这样的风格超过20年了.)


其它建议

  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()

注释

同代码不一致的注释比没注释更差.当代码修改时,始终优先更新注释! 注释应该是完整的句子. 如果注释是一个短语或句子,首字母应该大写, 除非他是一个以小写字母开头的标识符(永远不要修改标识符的大小写). 如果注释很短,最好省略末尾的句号(period?结尾句末的停顿?也可以是逗号吧,) 注释块通常由一个或多个由完整句子构成的段落组成,每个句子应该以句号结尾. 你应该在句末,句号后使用两个空格,以便使Emacs的断行和填充工作协调一致 (译按:应该说是使这两种功能正常工作,". "给出了文档结构的提示). 用英语书写时,断词和空格是可用的. 非英语国家的Python程序员:请用英语书写你的注释,除非你120%的确信 这些代码不会被不懂你的语言的人阅读.

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

-- CodeCommentingRule


注释块

注释块通常应用于跟随着一些(或者全部)代码并和这些代码有着相同的缩进层次. 注释块中每行以'#'和一个空格开始(除非他是注释内的缩进文本). 注释块内的段落以仅含单个'#'的行分割. 注释块上下方最好有一空行包围(或上方两行下方一行,对一个新函数定义段的注释).


行内注释

(inline?内联?翻成"行内"比较好吧)

x = x+1                 # Increment x
x = x+1                 # Increment x
x = x+1                 # Compensate for border
x = x+1                 # Compensate for border


文档化

Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized inPEP 257. 应该一直遵守编写好的文档字符串(又名"docstrings")的约定(?实在不知道怎么译)

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) (我觉得叫"注记"更好)

如果你要将RCS或CVS的杂项(crud)包含在你的源文件中,按如下做.

  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


命名约定

Python库的命名约定有点混乱,所以我们将永远不能使之变得完全一致--- 不过还是有公认的命名规范的. 新的模块和包(包括第三方的框架)必须符合这些标准,但对已有的库存在不同风格的, 保持内部的一致性是首选的.


描述:命名风格

(Descriptive: Naming Styles)

有许多不同的命名风格.以下的有助于辨认正在使用的命名风格,独立于它们的作用. 以下的命名风格是众所周知的:

os.stat()函数返回一个tuple,
 他的元素传统上有象st_mode, st_size, st_mtime等等这样的名字.
X11库的所有公开函数以X开头.

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

另外,以下用下划线作前导或结尾的特殊形式是被公认的(这些通常可以和任何习惯组合(使用?)):

       **(例如,"from M import *"不会导入以下划线开头的对象). 
      ** "Tkinter.Toplevel(master, class_='ClassName')". 


说明:命名约定

应避免的名字


模块名


类名


异常名


全局变量名


函数名


方法名和实例变量


继承的设计

始终要确定一个类中的方法和实例变量是否要被公开. 通常,永远不要将数据变量公开,除非你实现的本质上只是记录. 人们总是更喜欢给类提供一个函数的接口作为替换 (Python 2.2 的一些开发者在这点上做得非常漂亮). 同样,确定你的属性是否应为私有的.私有与非公有的区别在于: 前者永远不会被用在一个派生类中,而后者可能会. 是的,你应该在大脑中就用继承设计好了你的类. 私有属性必须有两个前导下划线,无后置下划线. 非公有属性必须有一个前导下划线,无后置下划线. 公共属性没有前导和后置下划线,除非它们与保留字冲突, 在此情况下,单个后置下划线比前置或混乱的拼写要好, 例如:class_优于klass. 最后一点有些争议; 如果相比class_你更喜欢klass,那么这只是一致性问题.


设计建议

  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):

在Python 2.2 类型模块为此定义了StringTypes类型, 例如:

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

在Python 2.0和2.1,你应该这样做:

  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:

-- ZoomQuiet (2005-01-26)

--- hoxide 初译 dreamingk 校对发布 040724
--- xyb 重新排版 040915
--- ZoomQuiet MoinMoin 美化 050610
个人工具
名字空间
变换
导航
工具箱