Google开源项目风格指南

Python是Google主要的脚本语言。这本风格指南主要包含的是针对python的编程规范。

Google开源项目风格指南-Python风格指南包含以下两个主要内容

1. Python语言规范
2. Python风格规范

文档地址： Google开源项目风格指南

一. Python语言规范

1.Lint

对你的代码运行pylint,pylint是一个在Python源代码中查找bug的工具.

可以捕获容易忽视的错误, 例如输入错误, 使用未赋值的变量等.

2.导入

仅对包和模块使用导入.并且必要时使用as

3.包

使用模块的全路径名来导入每个模块

4.异常

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

异常必须遵守特定条件:

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

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

   class Error(Exception):
       pass
   

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

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

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

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

   try:
       raise Error
   except Error as error:
       pass
   

5.全局变量

避免全局变量,导入时可能改变模块行为, 因为导入模块时会对模块级变量赋值.

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

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

6.嵌套/局部/内部类或函数

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

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

优点：允许定义仅用于有效范围的工具类和函数.

7.列表推导(List Comprehensions)

可以在简单情况下使用,复杂的列表推导或者生成器表达式可能难以阅读.

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

# Yes:
result = []
for x in range(10):
    for y in range(5):
        if x * y > 10:
            result.append((x, y))

for x in xrange(5):
    for y in xrange(5):
        if x != y:
            for z in xrange(5):
                if y != z:
                    yield (x, y, z)

return ((x, complicated_transform(x))
        for x in long_generator_function(parameter)
        if x is not None)

squares = [x * x for x in range(10)]

eat(jelly_bean for jelly_bean in jelly_beans
    if jelly_bean.color == 'black')

# No:
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

return ((x, y, z)
        for x in xrange(5)
        for y in xrange(5)
        if x != y
        for z in xrange(5)
        if y != z)

8.默认迭代器和操作符

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

# 内建类型也定义了迭代器方法. 优先考虑这些方法, 而不是那些返回列表的方法. 
# 当然，这样遍历容器时，你将不能修改容器.

# Yes:  
for key in adict: ...
if key not in adict: ...
if obj in alist: ...
for line in afile: ...
for k, v in dict.iteritems(): ...
  
# No: 
for key in adict.keys(): ...
if not adict.has_key(key): ...
for line in afile.readlines(): ...

9.生成器

按需使用生成器.

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

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

10.Lambda函数

适用于单行函数.

优点：方便。

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

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

11.条件表达式

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

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

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

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

12.默认参数值

适用于大部分情况。鼓励使用, 不过有如下注意事项:

不要在函数或方法定义中使用可变对象作为默认值.

# 不要在函数或方法定义中使用可变对象作为默认值.
Yes: def foo(a, b=None):
         if b is None:
             b = []
No:  def foo(a, b=[]):
         ...
No:  def foo(a, b=time.time()):  # The time the module was loaded???
         ...
No:  def foo(a, b=FLAGS.my_thing):  # sys.argv has not yet been parsed...
         ...

13.True/False的求值

尽可能使用隐式false,

Python在布尔上下文中会将某些值求值为false. 按简单的直觉来讲, 就是所有的”空”值都被认为是false.

因此0， None, [], {}, “” 都被认为是false.

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

结论:

尽可能使用隐式的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比较.

   Yes: if not users:
            print 'no users'
   
        if foo == 0:
            self.handle_zero()
   
        if i % 10 == 0:
            self.handle_multiple_of_ten()
   
   No:  if len(users) == 0:
            print 'no users'
   
        if foo is not None and not foo:
            self.handle_zero()
   
        if not i % 10:
            self.handle_multiple_of_ten()
   

6. 注意‘0’(字符串)会被当做true.

14.函数与方法装饰器

如果好处很显然, 就明智而谨慎的使用装饰器

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

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

结论:

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

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

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

15.线程

优先使用Queue模块的 Queue 数据类型作为线程间的数据通信方式.

另外, 使用threading模块及其锁原语(locking primitives).

了解条件变量的合适使用方式, 这样你就可以使用 threading.Condition 来取代低级别的锁了.

16.威力过大的特性

避免使用这些特性

定义:

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

优点:

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

缺点:

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

结论:

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

二. Python风格规范

1.分号

不要在行尾加分号, 也不要用分号将两条命令放在同一行.

2.行长度

每行不超过80个字符 例外:1.长的导入模块语句。2.注释里的URL

3.括号

宁缺毋滥的使用括号

除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号. 不过在元组两边使用括号是可以的

Yes: if foo:
         bar()
     while x:
         x = bar()
     if x and y:
         bar()
     if not x:
         bar()
     return foo
     for (x, y) in dict.items(): ...
No:  if (x):
         bar()
     if not(x):
         bar()
     return (foo)

4.缩进

用4个空格来缩进代码,绝对不要用tab, 也不要tab和空格混用.

5.空行

顶级定义之间空两行, 方法定义之间空一行

6.空格

按照标准的排版规范来使用标点两边的空格

# 括号内不要有空格.

Yes: spam(ham[1], {eggs: 2}, [])
No:  spam( ham[ 1 ], { eggs: 2 }, [ ] )
  
# 不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加(除了在行尾).
Yes: if x == 4:
         print x, y
     x, y = y, x
No:  if x == 4 :
         print x , y
     x , y = y , x

# 参数列表, 索引或切片的左括号前不应加空格.
Yes: spam(1)
no: spam (1)
Yes: dict['key'] = list[index]
No:  dict ['key'] = list [index]

  #在二元操作符两边都加上一个空格, 比如赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔(and, or, not). 至于算术操作符两边的空格该如何使用, 需要你自己好好判断. 不过两侧务必要保持一致.

Yes: x == 1
No:  x<1

# 当’=’用于指示关键字参数或默认参数值时, 不要在其两侧使用空格.
Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No:  def complex(real, imag = 0.0): return magic(r = real, i = imag)

# 不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #, =等):
Yes:
     foo = 1000  # comment
     long_name = 2  # comment that should not be aligned

     dictionary = {
         "foo": 1,
         "long_name": 2,
         }
No:
     foo       = 1000  # comment
     long_name = 2     # comment that should not be aligned

     dictionary = {
         "foo"      : 1,
         "long_name": 2,
         }

7.Shebang

大部分.py文件不必以#!作为文件的开始. 根据 PEP-394 , 程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始.

在计算机科学中, Shebang (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)

#!先用于帮助内核找到Python解释器, 但是在导入模块时, 将会被忽略. 因此只有被直接执行的文件中才有必要加入#!.

8.注释

确保对模块, 函数, 方法和行内注释使用正确的风格

9.类

如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.

Yes: class SampleClass(object):
         pass


     class OuterClass(object):

         class InnerClass(object):
             pass


     class ChildClass(ParentClass):
         """Explicitly inherits from another class already."""
No: class SampleClass:
        pass


    class OuterClass:

        class InnerClass:
            pass
# 继承自 object 是为了使属性(properties)正常工作, 并且这样可以保护你的代码, 使其不受 PEP-3000 的一个特殊的潜在不兼容性影响. 这样做也定义了一些特殊的方法, 这些方法实现了对象的默认语义, 包括 __new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .

10.字符串

即使参数都是字符串, 使用%操作符或者格式化方法格式化字符串. 不过也不能一概而论, 你需要在+和%之间好好判定.

Yes: x = a + b
     x = '%s, %s!' % (imperative, expletive)
     x = '{}, {}!'.format(imperative, expletive)
     x = 'name: %s; score: %d' % (name, n)
     x = 'name: {}; score: {}'.format(name, n)
No: x = '%s%s' % (a, b)  # use + in this case
    x = '{}{}'.format(a, b)  # use + in this case
    x = imperative + ', ' + expletive + '!'
    x = 'name: ' + name + '; score: ' + str(n)

# 避免在循环中用+和+=操作符来累加字符串. 由于字符串是不可变的, 这样做会创建不必要的临时对象, 并且导致二次方而不是线性的运行时间. 作为替代方案, 你可以将每个子串加入列表, 然后在循环结束后用 .join 连接列表. (也可以将每个子串写入一个 cStringIO.StringIO 缓存中.)

Yes: items = ['<table>']
     for last_name, first_name in employee_list:
         items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
     items.append('</table>')
     employee_table = ''.join(items)
No: employee_table = '<table>'
    for last_name, first_name in employee_list:
        employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
    employee_table += '</table>'

11.文件和sockets

在文件和sockets结束时, 显式的关闭它.

# 推荐使用 “with”语句 以管理文件:

with open("hello.txt") as hello_file:
    for line in hello_file:
        print line

12.TODO注释

为临时代码使用TODO注释, 它是一种短期解决方案. 不算完美, 但够好了.

TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么. 主要目的是为了有一个统一的TODO格式, 这样添加注释的人就可以搜索到(并可以按需提供更多细节). 写了TODO注释并不保证写的人会亲自解决问题. 当你写了一个TODO, 请注上你的名字.

# TODO(kl@gmail.com): Use a "*" here for string repetition.
# TODO(Zeke) Change this to use relations.

13.导入格式

每个导入应该独占一行

14.语句

通常每个语句应该独占一行

# 不过, 如果测试结果与测试语句在一行放得下, 你也可以将它们放在同一行. 如果是if语句, 只有在没有else时才能这样做. 特别地, 绝不要对 try/except 这样做, 因为try和except不能放在同一行.

Yes:

  if foo: bar(foo)
No:

  if foo: bar(foo)
  else:   baz(foo)

  try:               bar(foo)
  except ValueError: baz(foo)

  try:
      bar(foo)
  except ValueError: baz(foo)

15.访问控制

在Python中, 对于琐碎又不太重要的访问函数, 你应该直接使用公有变量来取代它们, 这样可以避免额外的函数调用开销. 当添加更多功能时, 你可以用属性(property)来保持语法的一致性.

16.命名

整个项目中所有的名字都要遵循规范和有意义的定义

Python之父Guido推荐的规范

| Type | Public | Internal | | ————————– | —————— | ———————————————————— | | Modules | lower_with_under | _lower_with_under | | Packages | lower_with_under | | | Classes | CapWords | _CapWords | | Exceptions | CapWords | | | Functions | lower_with_under() | _lower_with_under() | | Global/Class Constants | CAPS_WITH_UNDER | _CAPS_WITH_UNDER | | Global/Class Variables | lower_with_under | _lower_with_under | | Instance Variables | lower_with_under | _lower_with_under (protected) or __lower_with_under (private) | | Method Names | lower_with_under() | _lower_with_under() (protected) or __lower_with_under() (private) | | Function/Method Parameters | lower_with_under | | | Local Variables | lower_with_under | |

17.Main

即使是一个打算被用作脚本的文件, 也应该是可导入的. 并且简单的导入不应该导致这个脚本的主功能(main functionality)被执行, 这是一种副作用. 主功能应该放在一个main()函数中.

在Python中, pydoc以及单元测试要求模块必须是可导入的.

你的代码应该在执行主程序前总是检查 if __name__ == '__main__' ,

这样当模块被导入时主程序就不会被执行.

def main():
      ...

if __name__ == '__main__':
    main()

所有的顶级代码在模块导入时都会被执行.

要小心不要去调用函数, 创建对象, 或者执行那些不应该在使用pydoc时执行的操作.

临别赠言

请务必保持代码的一致性

如果你正在编辑代码, 花几分钟看一下周边代码, 然后决定风格. 如果它们在所有的算术操作符两边都使用空格, 那么你也应该这样做. 如果它们的注释都用标记包围起来, 那么你的注释也要这样.

制定风格指南的目的在于让代码有规可循, 这样人们就可以专注于”你在说什么”, 而不是”你在怎么说”. 我们在这里给出的是全局的规范, 但是本地的规范同样重要. 如果你加到一个文件里的代码和原有代码大相径庭, 它会让读者不知所措. 避免这种情况.