python 编程的 Style Guide

Python 的作者既优雅又高冷又鬼毛的再 PEP8 里规定了 Python 程序编写规范。（风格和格式）

一、基本观念

　　1、可读性之上，代码被读的次数肯定比被写的次数多。因此作者十分重视代码的可读性，后文中的很多规定都是基于这个出发点考虑的。

　　2、一致性次之，如果所有的代码的 style 与本指南不符，有限考虑一致性，但是新编写的模块有限遵风格指南；

二、具体操作

　　1、布局和格式

　　　　+ 缩进：优先用四个空格而不是制表符（tab）

　　　　+ 多行连读语句：对齐。几个正面的例子：

# 括号内开头对齐
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
 
# Hanging indent: 括号第一行不填，第二行开始括号内的部分加倍缩进（多4个空格）
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

　　　　+ 多行构赋值：后半括号要独立一行，且和前面的行对齐，两种方式均可：

my_list = [
    , , ,
    , , ,
    ]
my_list = [
    , , ,
    , , ,
]

　　　　+ 行的长度少于 72 个字符：主要时为了便于分屏对比代码（作者操心命）。

　　　　　换行的操作：优先用括号把并列的长语句括起来。然后就可以再连接处换行了，比如 with 或者 assert 语句，再用反斜杠。

　　　　+ 在操作符（+、-、*、\）之前换行：方便阅读时快速理解操作符后面的内容是被如何操作的，

　　　　+ 空白行：顶层 function 和 class 前后各两行，method 前后各一行

　　　　+ 导入 import ：不同的库每个导入各占一行，相同的库里多个模块可以在一行导入，导入顺序：标准库 -> 空白行，第三方库、本地库

　　　　+ 各种符合语句，最好各占一行，为了可读性，不要再一行内出现多个语句

　　2、符号

　　　　+ 引号：string 的两侧单引号双引号都可以，string 的内容里如果又但单引号，外面的就用双引号，反之亦然，尽量不适用反斜杠类 escape，影响可读性。

　　　　+ 空白符：

　　　　　　1、各种括号的内部不直接用空白符　

YES: spam(ham[], {egg: })
No: spam( ham(  ), { egg:  })

　　　　　　2、逗号分号冒号前面不直接用空白符

Yes: if x == : print x, y; x, y = y, x
No:  if x ==  : print x , y ; x , y = y , x

　　　　　　3、function 和 variable 名字和括号之间不加空白符

　　　　　　4、避免在行尾使用多余的空白符，影响某些符号的运行，主要是你很难发现

　　　　　　5、运算符两端要各加且只加一个空白符，遇到多层优先级的运算，只在最低优先级的运算符两侧加空白符：

# Yes
i = i +
submitted +=
x = x* -
hypot2 = x*x + y*y
c = (a+b) * (a-b)
 
# No
i=i+
submitted +=
x = x *  -
hypot2 = x * x + y * y
c = (a + b) * (a - b)

　　　　　　6、关键字参数的赋值等号不用空白符

def complex(real, imag=0.0):
    return magic(r=real, i=imag)

　　　　+ 末尾逗号：tuple 和 list的最后一项是可以接逗号的

　　　　　　　　这里说明一下：如果 tuple 和 list 是分行构建的，且每一行左后可以接一个逗号，方便以后的扩展保持统一格式：如果是在同一行构建的，则没必要最后接一个逗号

　　　3、注释

　　　　+ 注释是保证注解的内容保持更新的，不然和代码不符，还真倒不如注释

　　　　+ 注释要说人话，用完整的语句编写，开头大写，句尾加句号

　　　　+ 注释据句尾句号后加两个空白符在换行

　　　　+ 大段注释，每一行开头 # 开头，几个空白符在写内容，段落之间的空行也用 # 开头

　　　　+ 同行注释尽量不使用，干扰阅读代码。如果某些特殊情况必须使用，和代码直接保持两个以上的空白符

　　　　+ docstring ：给所有公开的模块，函数。类写 dcostring. 私有的就不用写了，用注释时代替，

　　　　　　这种注释应该出现在 def 的后一行，默认用三双引号来做

　　　　　　docstring ：对于多行的 docstring ，结尾的三引号要独占一行

　　　　4、命名

　　　　　　+ 命名的风格又很多种，Python 基本使用的是 lower_case_with_underscore

　　　　　　+ 使用 _single_leading_underscore:：表示弱的内部使用，在 from X import * 是不会导入这一类对象

　　　　　　+ 使用 single_tailing_underscore_：为了略微改变那些和 Python 的 keyword 冲突的命名

　　　　　　+ 使用__double_leading_underscore：类的外面是无法调用这个对象

　　　　　　+ 首位都有双下划线的命名只限 python 内部使用，不要随意起这种名

　　　　　　+ 不要只用小写的 ”i“ 大写的 ”O“，容易引起误解

　　　　　　+ package 和 moudle 的命名用 lower_case_with_underscore

　　　　　　+ 类的命名使用 CapWords

　　　　　　+ Class 内部的命名，能使用非公开就用非公开，因为把一个 attribute 由非公开变为公开要比反过来容易太多

　　　　5、编程过程中的风格建议

　　　　　　+ 和 None 做比较时永远用 is \ is not 而不是 ==

　　　　　　 + 用 if x in not y 而不是 if not x is y：更贴经自然语言

　　　　　　+ 定义函数的时候，永远用 def 而不是把一个 lambda 函数赋给一个变量名。lambda的唯一使用场景应该是一个复杂的表达里嵌入使用

　　　　　　+ 在使用 Exception 的时候，从 Exception 到处为不是 BaseException

　　　　　　+ 在使用 try...except ... 排除意外的时候，明确规定 except 的意外情况而不是直接使用 ‘except’:，这是确保不会把 SystemExit 算进去，那样的话 contrl-c 衲衣操作

　　　　　　+ 保证Return 的一致性：　　一个函数里要么都不 return，要么每种情况的 return 都明确规定，即便return None

def foo(x):
    if x >= :
        return math.sqrt(x)
    else:
        return None
 
def bar(x):
    if x < :
        return None
    return math.sqrt(x)

　　　　+ 永远优先使用 string 的 methods 不是直接使用 string module，比如用 .startwith()， .endwith() 来代替 slicing 作比较

　　　　+ 记住空的有序容器比如 tuple set string list 的布尔值是 False

　　　　+ 永远不要把布尔值和 True / False 作比较，直接用它的真假来控制流程