Google 开源项目风格(一) - jerry

Welcome to Aiiyx !

Google 开源项目风格(一)

Python语言规范

1、导入, 仅对包和模块使用导入

使用 import x 来导入包和模块.

使用 from x import y , 其中x是包前缀, y是不带前缀的模块名.

使用 from x import y as z, 如果两个要导入的模块都叫做y或者y太长了.

2、包, 使用模块的全路径名来导入每个模块

所有的新代码都应该用完整包名来导入每个模块.

应该像下面这样导入:

3、异常, 允许使用异常, 但必须小心

异常必须遵守特定条件:

1>、像这样触发异常: raise MyException("Error message") 或者 raise MyException . 不要使用两个参数的形式( raise MyException, "Error message" )或者过时的字符串异常( raise "Error message" ).

2>、 模块或包应该定义自己的特定域的异常基类, 这个基类应该从内建的Exception类继承. 模块的异常基类应该叫做”Error”.

3>、永远不要使用except:语句来捕获所有异常,也不要捕获Exception 或者StandardError, 除非你打算重新触发该异常,或者你已经在当前线程的最外层(记得还是要打印一条错误消息).在异常这方面, Python非常宽容,except: 真的会捕获包括Python语法错误在内的任何错误.使用except: 很容易隐藏真正的bug.

4>、尽量减少try/except块中的代码量. try块的体积越大, 期望之外的异常就越容易被触发. 这种情况下, try/except块将隐藏真正的错误.

5>、使用finally子句来执行那些无论try块中有没有异常都应该被执行的代码. 这对于清理资源常常很有用, 例如关闭文件.

6>、 当捕获异常时, 使用 as 而不要用逗号. 例如 :

4、全局变量, 避免全局变量

避免使用全局变量, 用类变量来代替. 但也有一些例外:

  1. 脚本的默认选项.
  2. 模块级常量. 例如: PI = 3.14159. 常量应该全大写, 用下划线连接.
  3. 有时候用全局变量来缓存值或者作为函数返回值很有用.
  4. 如果需要, 全局变量应该仅在模块内部可用, 并通过模块级的公共函数来访问.

5、嵌套/局部/内部类或函数

鼓励使用嵌套/本地/内部类或函数

类可以定义在方法, 函数或者类中. 函数可以定义在方法或函数中. 封闭区间中定义的变量对嵌套函数是只读的.

6、列表推导(List Comprehensions), 可以在简单情况下使用

列表推导(list comprehensions)生成器表达式(generator expression)提供了一种简洁高效的方式来创建列表和迭代, 而不必借助map(), filter(), 或者lambda.

优点:简单的列表推导可以比其它的列表创建方法更加清晰简单. 生成器表达式可以十分高效, 因为它们避免了创建整个列表.

缺点:复杂的列表推导或者生成器表达式可能难以阅读.

结论: 适用于简单情况. 每个部分应该单独置于一行: 映射表达式, for语句, 过滤器表达式. 禁止多重for语句或过滤器表达式. 复杂情况下还是使用循环.

7、默认迭代器和操作符

如果类型支持, 就使用默认迭代器和操作符. 比如列表, 字典及文件等.

定义:容器类型, 像字典和列表, 定义了默认的迭代器和关系测试操作符(in和not in)

优点:默认操作符和迭代器简单高效, 它们直接表达了操作, 没有额外的方法调用. 使用默认操作符的函数是通用的. 它可以用于支持该操作的任何类型.

缺点:你没法通过阅读方法名来区分对象的类型(例如, has_key()意味着字典). 不过这也是优点.

结论:如果类型支持, 就使用默认迭代器和操作符, 例如列表, 字典和文件. 内建类型也定义了迭代器方法. 优先考虑这些方法, 而不是那些返回列表的方法. 当然,这样遍历容器时,你将不能修改容器.

8、生成器, 按需使用生成器.

定义:所谓生成器函数, 就是每当它执行一次生成(yield)语句, 它就返回一个迭代器, 这个迭代器生成一个值. 生成值后, 生成器函数的运行状态将被挂起, 直到下一次生成.

优点:简化代码, 因为每次调用时, 局部变量和控制流的状态都会被保存. 比起一次创建一系列值的函数, 生成器使用的内存更少.

缺点:没有.

结论:鼓励使用. 注意在生成器函数的文档字符串中使用”Yields:”而不是”Returns:”.

9、Lambda函数, 适用于单行函数

与语句相反, lambda在一个表达式中定义匿名函数. 常用于为map()和filter()之类的高阶函数定义回调函数或者操作符.

优点:方便.

缺点:比本地函数更难阅读和调试. 没有函数名意味着堆栈跟踪更难理解. 由于lambda函数通常只包含一个表达式, 因此其表达能力有限.

结论:适用于单行函数. 如果代码超过60-80个字符, 最好还是定义成常规(嵌套)函数.

对于常见的操作符,例如乘法操作符,使用 operator 模块中的函数以代替lambda函数. 例如, 推荐使用 operator.mul , 而不是 lambda x, y: x * y .

10、条件表达式, 适用于单行函数

条件表达式是对于if语句的一种更为简短的句法规则. 例x = 1 if cond else 2 .

优点:比if语句更加简短和方便.

缺点:比if语句难于阅读. 如果表达式很长, 难于定位条件.

结论:适用于单行函数. 在其他情况下,推荐使用完整的if语句.

11、默认参数值, 适用于大部分情况.

你可以在函数参数列表的最后指定变量的值, 例如, def foo(a, b = 0):. 如果调用foo时只带一个参数, 则b被设为0. 如果带两个参数, 则b的值等于第二个参数.

优点:你经常会碰到一些使用大量默认值的函数, 但偶尔(比较少见)你想要覆盖这些默认值. 默认参数值提供了一种简单的方法来完成这件事, 你不需要为这些罕见的例外定义大量函数. 同时, Python也不支持重载方法和函数,支持重写, 默认参数是一种”仿造”重载行为的简单方式.

缺点:默认参数只在模块加载时求值一次. 如果参数是列表或字典之类的可变类型, 这可能会导致问题. 如果函数修改了对象(例如向列表追加项), 默认值就被修改了.

结论:鼓励使用, 不过有如下注意事项:不要在函数或方法定义中使用可变对象作为默认值.

12、属性(properties)

访问和设置数据成员时, 你通常会使用简单, 轻量级的访问和设置函数. 建议用属性(properties)来代替它们.

一种用于包装方法调用的方式. 当运算量不大, 它是获取和设置属性(attribute)的标准方式.

优点:通过消除简单的属性(attribute)访问时显式的get和set方法调用, 可读性提高了. 允许懒惰的计算. 用Pythonic的方式来维护类的接口. 就性能而言, 当直接访问变量是合理的, 添加访问方法就显得琐碎而无意义. 使用属性(properties)可以绕过这个问题. 将来也可以在不破坏接口的情况下将访问方法加上.

缺点:属性(properties)是在get和set方法声明后指定, 这需要使用者在接下来的代码中注意: set和get是用于属性(properties)的(除了用@property装饰器创建的只读属性). 必须继承自object类. 可能隐藏比如操作符重载之类的副作用. 继承时可能会让人困惑.

结论:你通常习惯于使用访问或设置方法来访问或设置数据, 它们简单而轻量. 不过我们建议你在新的代码中使用属性. 只读属性应该用@property装饰器 来创建.

如果子类没有覆盖属性, 那么属性的继承可能看上去不明显. 因此使用者必须确保访问方法间接被调用, 以保证子类中的重载方法被属性调用(使用模板方法设计模式).

13、True/False的求值, 尽可能使用隐式false

Python在布尔上下文中会将某些值求值为false. 按简单的直觉来讲, 就是所有的”空”值都被认为是false. 因此0, None, [], {}, “” 都被认为是false.

优点:使用Python布尔值的条件语句更易读也更不易犯错. 大部分情况下, 也更快.

缺点:对C/C++开发人员来说, 可能看起来有点怪.

结论:尽可能使用隐式的false, 例如: 使用if foo:而不是if foo != []: . 不过还是有一些注意事项需要你铭记在心:

  1. 永远不要用==或者!=来比较单件, 比如None. 使用is或者is not.
  2. 注意: 当你写下 if x: 时, 你其实表示的是 if x is not None . 例如: 当你要测试一个默认值是None的变量或参数是否被设为其它值. 这个值在布尔语义下可能是false!
  3. 永远不要用==将一个布尔量与false相比较. 使用 if not x: 代替. 如果你需要区分false和None, 你应该用像 if not x and x is not None: 这样的语句.
  4. 对于序列(字符串, 列表, 元组), 要注意空序列是false. 因此 if not seq: 或者 if seq: 比 if len(seq): 或 if not len(seq): 要更好.
  5. 处理整数时, 使用隐式false可能会得不偿失(即不小心将None当做0来处理). 你可以将一个已知是整型(且不是len()的返回结果)的值与0比较.
  6. 注意‘0’(字符串)会被当做true.

14、过时的语言特性

尽可能使用字符串方法取代字符串模块. 使用函数调用语法取代apply(). 使用列表推导, for循环取代filter(), map()以及reduce().

当前版本的Python提供了大家通常更喜欢的替代品.结论:

我们不使用不支持这些特性的Python版本, 所以没理由不用新的方式.

15、词法作用域(Lexical Scoping), 推荐使用

嵌套的Python函数可以引用外层函数中定义的变量其实就是闭包), 但是不能够对它们赋值. 变量绑定的解析是使用词法作用域, 也就是基于静态的程序文本. 对一个块中的某个名称的任何赋值都会导致Python将对该名称的全部引用当做局部变量, 甚至是赋值前的处理. 如果碰到global声明, 该名称就会被视作全局变量. (啰嗦一大堆)

优点:通常可以带来更加清晰, 优雅的代码. 尤其会让有经验的Lisp和Scheme(还有Haskell, ML等)程序员感到欣慰.缺点:

结论:鼓励使用.

16、函数与方法装饰器, 如果好处很显然, 就明智而谨慎的使用装饰器

用于函数及方法的装饰器 (也就是@标记). 最常见的装饰器是@classmethod 和@staticmethod, 用于将常规函数转换成类方法或静态方法. 不过, 装饰器语法也允许用户自定义装饰器. 特别地, 对于某个函数my_decorator, 下面的两段代码是等效的:

优点:优雅的在函数上指定一些转换. 该转换可能减少一些重复代码, 保持已有函数不变(enforce invariants), 等.

缺点:装饰器可以在函数的参数或返回值上执行任何操作, 这可能导致让人惊异的隐藏行为. 而且, 装饰器在导入时执行. 从装饰器代码的失败中恢复更加不可能.

结论:如果好处很显然, 就明智而谨慎的使用装饰器. 装饰器应该遵守和函数一样的导入和命名规则. 装饰器的python文档应该清晰的说明该函数是一个装饰器. 请为装饰器编写单元测试.

避免装饰器自身对外界的依赖(即不要依赖于文件, socket, 数据库连接等), 因为装饰器运行时这些资源可能不可用(由 pydoc 或其它工具导入). 应该保证一个用有效参数调用的装饰器在所有情况下都是成功的.

装饰器是一种特殊形式的”顶级代码”. 参考后面关于 Main 的话题.

17、线程, 不要依赖内建类型的原子性.

虽然Python的内建类型例如字典看上去拥有原子操作, 但是在某些情形下它们仍然不是原子的(即: 如果__hash__或__eq__被实现为Python方法)且它们的原子性是靠不住的. 你也不能指望原子变量赋值(因为这个反过来依赖字典).

优先使用Queue模块的 Queue 数据类型作为线程间的数据通信方式. 另外, 使用threading模块及其锁原语(locking primitives). 了解条件变量的合适使用方式, 这样你就可以使用 threading.Condition 来取代低级别的锁了.

18、威力过大的特性, 避免使用这些特性

Python是一种异常灵活的语言, 它为你提供了很多花哨的特性, 诸如元类(metaclasses), 字节码访问, 任意编译(on-the-fly compilation), 动态继承, 对象父类重定义(object reparenting), 导入黑客(import hacks), 反射, 系统内修改(modification of system internals), 等等.

优点:强大的语言特性, 能让你的代码更紧凑.

缺点:使用这些很”酷”的特性十分诱人, 但不是绝对必要. 使用奇技淫巧的代码将更加难以阅读和调试. 开始可能还好(对原作者而言), 但当你回顾代码, 它们可能会比那些稍长一点但是很直接的代码更加难以理解.

结论:在你的代码中避免这些特性.