0、Python 代码风格指南

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：lr_scheduler.py
• 类名和异常：首字母大写，单词直接连在一起，eg：CapWords
• 全局变量：全大写字母，单词之间用下划线分割，eg：CAPS_WITH_UNDER
• 其它(普通变量、模块、包、函数、方法)：全小写字母，单词之间用下划线分割，eg：lower_with_under
• 内部属性：受保护的实例属性一般在最前面加一个下划线_，私有的实例属性一般在最前面加两个下划线__
• 单下划线 _：用作临时变量或者无意义变量的名称（不关心）
• 后置单下划线 var_：用于避免与 python 关键字发生命名冲突
• 前后双下划线 __var__：python 语言定义的特殊方法
  

---

五、语句

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

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