#  Google开源项目风格指南

> Python是Google主要的脚本语言。这本风格指南主要包含的是针对python的编程规范。
>
> Google开源项目风格指南-Python风格指南包含以下两个主要内容
>
> 1. Python语言规范
> 2. Python风格规范
>
> 文档地址：[ Google开源项目风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/contents/)

## 一.  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”.

   > ```python
   > class Error(Exception):
   >     pass
   > ```

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

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

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

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

   > ```python
   > try:
   >     raise Error
   > except Error as error:
   >     pass
   > ```

### 5.全局变量

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

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

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

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

> 鼓励使用嵌套/本地/内部类或函数
>
> 类可以定义在方法, 函数或者类中. 函数可以定义在方法或函数中. 封闭区间中定义的变量对嵌套函数是只读的.
>
> 优点：允许定义仅用于有效范围的工具类和函数.

### 7.列表推导(List Comprehensions)

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

```python
# 适用于简单情况. 
# 每个部分应该单独置于一行: 映射表达式, 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.默认迭代器和操作符

> 如果类型支持, 就使用默认迭代器和操作符. 比如列表, 字典及文件等.
>
> ```python
> # 内建类型也定义了迭代器方法. 优先考虑这些方法, 而不是那些返回列表的方法. 
> # 当然，这样遍历容器时，你将不能修改容器.
> 
> # 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.默认参数值

> 适用于大部分情况。鼓励使用, 不过有如下注意事项:
>
> 不要在函数或方法定义中使用可变对象作为默认值.

```python
# 不要在函数或方法定义中使用可变对象作为默认值.
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比较.
>
>    ```python
>    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.括号

> 宁缺毋滥的使用括号
>
> 除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号. 不过在元组两边使用括号是可以的
>
> ```python
> 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.空格

> 按照标准的排版规范来使用标点两边的空格
>
> ```python
> # 括号内不要有空格.
> 
> 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](http://www.python.org/dev/peps/pep-0394/) , 程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始.
>
> 在计算机科学中, [Shebang](http://en.wikipedia.org/wiki/Shebang_(Unix)) (也称为Hashbang)是一个由井号和叹号构成的字符串行(#!), 其出现在文本文件的第一行的前两个字符. 在文件中存在Shebang的情况下, 类Unix操作系统的程序载入器会分析Shebang后的内容, 将这些内容作为解释器指令, 并调用该指令, 并将载有Shebang的文件路径作为该解释器的参数. 例如, 以指令#!/bin/sh开头的文件在执行时会实际调用/bin/sh程序.)
>
> \#!先用于帮助内核找到Python解释器, 但是在导入模块时, 将会被忽略. 因此只有被直接执行的文件中才有必要加入#!.

### 8.注释

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

### 9.类

> 如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.
>
> ```python
> 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.字符串

> 即使参数都是字符串, 使用%操作符或者格式化方法格式化字符串. 不过也不能一概而论, 你需要在+和%之间好好判定.
>
> ```python
> 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结束时, 显式的关闭它.
>
> ```python
> # 推荐使用 “with”语句 以管理文件:
> 
> with open("hello.txt") as hello_file:
>     for line in hello_file:
>         print line
> ```

### 12.TODO注释

> 为临时代码使用TODO注释, 它是一种短期解决方案. 不算完美, 但够好了.
>
> TODO注释应该在所有开头处包含”TODO”字符串, 紧跟着是用括号括起来的你的名字, email地址或其它标识符. 然后是一个可选的冒号. 接着必须有一行注释, 解释要做什么. 主要目的是为了有一个统一的TODO格式, 这样添加注释的人就可以搜索到(并可以按需提供更多细节). 写了TODO注释并不保证写的人会亲自解决问题. 当你写了一个TODO, 请注上你的名字.
>
> ```python
> # TODO(kl@gmail.com): Use a "*" here for string repetition.
> # TODO(Zeke) Change this to use relations.
> ```

### 13.导入格式

> 每个导入应该独占一行

### 14.语句

> 通常每个语句应该独占一行
>
> ```python
> # 不过, 如果测试结果与测试语句在一行放得下, 你也可以将它们放在同一行. 如果是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__'` , 

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

```python
def main():
      ...

if __name__ == '__main__':
    main()
```

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

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

## 临别赠言

**请务必保持代码的一致性**

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

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