Google 开源项目风格指南

所有的 Python 脚本文件都应在文件头标上如下标识或其兼容格式的标识：

# -*- coding:utf-8 -*-

设置编辑器，默认保存为 utf-8 格式。

##二、注释

• 推荐对每一个包、模块、类、函数（方法）写 docstrings，除非代码一目了然，非常简单。
• 为了提高可读性, 注释应该至少离开代码 2 个空格; # 号后面要空一格。

##三、格式
###1. 缩进

• Python 依赖缩进来确定代码块的层次，行首空白符主要有两种：tab 和空格。
• Never use tabs or mix tabs and spaces.
• 一般使用 4 个空格进行缩进。
• 对于行连接的情况, 你应该要么**垂直对齐换行的元素, 或者使用4空格的悬挂式缩进**(这时第一行不应该有参数):

Yes:   # Aligned with opening delimiter
       foo = long_function_name(var_one, var_two,
                                var_three, var_four)

       # Aligned with opening delimiter in a dictionary
       foo = {
           long_dictionary_key: value1 +
                                value2,
           ...
       }

       # 4-space hanging indent; nothing on first line
       foo = long_function_name(
           var_one, var_two, var_three,
           var_four)

       # 4-space hanging indent in a dictionary
       foo = {
           long_dictionary_key:
               long_dictionary_value,
           ...
       }
       

No:    # Stuff on first line forbidden
      foo = long_function_name(var_one, var_two,
          var_three, var_four)

      # 2-space hanging indent forbidden
      foo = long_function_name(
        var_one, var_two, var_three,
        var_four)

      # No hanging indent in a dictionary
      foo = {
          long_dictionary_key:
              long_dictionary_value,
              ...
      }

###2. 空格

• 一般要在双目运算符前后加空格，如：a = b + c
• “:”用在行尾时前后皆不加空格，如分枝、循环、函数和类定义语言；用在非行尾时右端加空格，如 dict 对象的定义：d = {'key': 'value'}
• 不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加空格(除了在行尾)。
• 当**’='用于指示关键字参数或默认参数值**时, 不要在其两侧使用空格，magic(r=real, i=imag) if i & (i-1) == 0 # 括号内的减号，其两侧也不需要空格

###3. 空行：顶级定义之间空两行, 方法定义之间空一行

• Two blank lines between top-level definitions, be they function or class definitions.
• One blank line between method definitions and between the class line and the first method.
• Use single blank lines as you judge appropriate within functions or methods.
• import 不同种类**(标准库、第三方库、自定义库)**的模块时加空行。

###4. 断行

• 不要在行尾加分号, 也不要用分号将两条命令放在同一行.
• 每行不超过80个字符。
• 不要使用反斜杠连接行。
• 在括号（包括圆括号、方括号和花括号）内换行，如：

class Edit(Widget):
    
    def __init__(self, parent, width,
				 font = FONT, color = BLACK, 
				 pos = POS, style = 0): 
        pass

• 类名和异常：首字母大写，单词直接连在一起，eg：CapWords
• 全局变量：全大写字母，单词之间用下划线分割，eg：CAPS_WITH_UNDER
• 其它(普通变量、模块、包、函数、方法)：全小写字母，单词之间用下划线分割，eg：lower_with_under
• 内部属性：受保护的实例属性一般在最前面加一个下划线，私有的实例属性一般在最前面加两个下划线
  

##五、语句

1. import 语句有以下几个原则需要遵守

   • 一条 import 语句只导入一个模块。
   • import 的次序：先 import Python 标准库，再 import 第三方库，最后 import 自己开发的项目中的其它库文件或者模块，这几种库中间用空行分隔开来。

2. 分枝和循环

• 不要写成一行
• 条件表达式的编写应该足够 pythonic，如以下形式的条件表达式是拙劣的：

if len(alist) != 0: do_something()
if alist != []: do_something()
if s != "": do_something()
if var != None: do_something()
if var != False: do_something()

# 注意，(seq, val)本身具有可判断性，所以，上面的语句应该写成：
if seq: 
    do_something() 
if var: 
    do_something()

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

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