测试开发技术网站

[TOC]
# 一、布局

## 1.1 缩进

* 每一级缩进使用4个空格
* 类似定义函数或者调用函数时参数过多的场景，有两种推荐缩进做法，一种是第一行有参数，换行后利用
括号默认的垂直对齐方式。另一种方式就是第一行没有参数，参数直接换行到下一行，此时
缩进需要比其他代码多缩进一级，便于轻松识别出不是其他的代码语句
* if语句中条件比较多需要换行时，推荐两种处理方式，一种是判断条件和代码之间
增加一行注释，另外一种就是对条件做更多一层的缩进，从而用于语句块中的代码区分开
* 当多行结构中使用的括号（小括号、方括号、花括号）的右括号另起一行的时候，可以与上一行的第一个字符对齐
或者也可以与下一行的第一个字符对齐

```python
    # 以下代码为推荐代码：
    def long_function_name(var_one,
                       var_two, 
                       var_three,
                       var_four):
        print(var_one)
  
    def long_function_name(
            var_one, var_two, var_three,
            var_four):
        print(var_one)
  
    foo = long_function_name(var_one, var_two,
                         var_three, var_four)
  
    foo = long_function_name(
        var_one, var_two,
        var_three, var_four)
    
    if (this_is_one_thing and
        that_is_another_thing):
        # 当满足某种条件时执行此分支.
        do_something()
  
    if (this_is_one_thing
            and that_is_another_thing):
        do_something()
  
    my_list = [
        1, 2, 3,
        4, 5, 6,
        ]
  
    result = some_function_that_takes_arguments(
        'a', 'b', 'c',
        'd', 'e', 'f',
        )
  
    my_list = [
        1, 2, 3,
        4, 5, 6,
    ]
    result = some_function_that_takes_arguments(
        'a', 'b', 'c',
        'd', 'e', 'f',
    )
    
    # 以下代码为不推荐代码
    def long_function_name(var_one,
        var_two,var_three,var_four):
        print(var_one)
  
    foo = long_function_name(var_one, var_two,
        var_three, var_four)
  
    if (this_is_one_thing and
        that_is_another_thing):
        do_something()

```
    
    
## 1.2 Tabs 键还是 空格键

* 空格是首选的缩进方式
* 如果使用tab键则所有缩进均需要使用tab键
* python3不允许同时使用空格和tab键
	
## 1.3 行最大长度

* 所有行限制最大字符数为79
   * 注释、字符串等文本行最大字符数限制72
   * 如果团队内达成一致认识，可以将代码行最大长度扩大到99，注释行仍然限制72
   * 一行代码过长时优先通过小括号，方括号，花括号来换行，而不是反斜线的方式
   
```python
   # 推荐做法
     def methond_to_show_code_set_in_multiline_with_bracket(first_paramp="",
                                                       second_param="",
                                                       third_param=""):
        pass
            
   # 不推荐做法
    def methond_to_show_code_set_in_multiline_with_bracket(first_paramp="",\
                                                       second_param="",\
                                                       third_param=""):
        pass
```
   
## 1.4 在二元运算符之前还是之后换行呢？

* 在很长的表示式中如果想换行推荐在二元操作符之前换行
```python
    # 推荐做法
    income = (gross_wages
            taxable_interest
            (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)
  
    # 不推荐做法
    income = (gross_wages  
          taxable_interest  
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)
```
	
## 1.5 空行
* 文件顶级的类或者函数定义的前后需要使用两个空行
* 类中方法定义前后使用一个空行

```python
# 注释

def func1():
	pass

class Demo1():

def method1(self):
	pass

def method2(self):
	pass

def func2():
	pass

class Demo2():
	pass

```

## 1.6 源文件编码

* 文件中不应有编码声明，默认均以UTF-8编码
    
## 1.7 imports

* 不同的包在不同的行导入，不推荐一行导入多个包
* 一行可以导入同一个包中的多个模块或类
* 导入总是文件的顶部，在模块注释和文档字符串之后，在模块的全局变量和常量之前
* 导入应该按照如顺序导入，在每一组中间需要加入空行
* 标准库导入
* 第三方库导入
* 本地应用库导入
* 推荐使用绝对路径导入，可读性更好
* 避免使用通配符导入，如from xxx import *
	
```python
    # 推荐做法
    import os
    import sys
    from subprocess import Popen, PIPE
    
    from flask import Flask
  
    # 不推荐做法
    import os,sys
    from subprocess import Popen, PIPE
    from flask import Flask
```
    
## 1.8 模块级的魔法函数名
* 像 __all__,__author__,__version__等模块级的魔法函数，应该放在文档字符串后面，并且在除了
    from __future__ import xxx 语句以外其他的import语句之前，如：
	
```python
    """This is the example module.
    
    This module does stuff.
    """
    
    from __future__ import barry_as_FLUFL
    
    __all__ = ['a', 'b', 'c']
    __version__ = '0.1'
    __author__ = 'Cardinal Biggles'
    
    import os
    import sys
```
	
# 二、字符串引号

* 单引号或者双引号均可以，只需要代码风格保持一致即可
   * 三引号推荐使用三个双引号
   
# 三、表达式和语句块中的空格

## 3.1 不能忍受的

* 下列情况下不允许使用空格
      * 紧跟在小括号、中括号、大括号后
      * 紧贴在逗号，分号或者冒号之前，注意在切片中的冒号，两边需要有相同数量的空格，当切片参数省略时，空格也必须省略
      * 紧贴在函数参数的左括号之前
      * 紧贴索引或者切片的左括号之前
      * 为了和赋值运算符对齐，在赋值运算符之前加多个空格
```python
      # 推荐做法
      spam(ham[1], {eggs: 2})
      if x == 4: print x, y; x, y = y, x
      ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
      ham[lower:upper], ham[lower:upper:], ham[lower::step]
      ham[lower offset : upper offset]
      ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
      ham[lower   offset : upper   offset]
      spam(1)
      dct['key'] = lst[index]
      x = 1
      y = 2
      long_variable = 3

# 不推荐做法
      spam( ham[ 1 ], { eggs: 2 } )
      if x == 4 : print x , y ; x , y = y , x
      ham[lower   offset:upper   offset]
      ham[1: 9], ham[1 :9], ham[1:9 :3]
      ham[lower : : upper]
      ham[ : upper]
      spam (1)
      dct ['key'] = lst [index]
      x             = 1
      y             = 2
      long_variable = 3
```

## 3.2 其他建议

* 避免在尾部添加空格
   * 总是在二元运算符两天各添加一个空格
   * 如果使用具有不同优先级的运算符，推荐在具有最低优先级的运算符周围加空格，但是最多使用一个空格，
   并且在二元运算符两边使用相同数量的空格
   * 在函数调用或定义中使用默认值或者指定参数的时候，=前后不要使用空格
   * 功能型注释应该使用冒号的一般性原则，并且在使用->的时候前后需要使用空格
   * 当给有类型备注的参数赋值的时候，在=两边添加空格，注意这里仅针对有类型备注说明的
   * 复合语句（一行中有多个语句）通常是不允许的
   
```python
   # 推荐做法
    i = i   1
    submitted  = 1
    x = x*2 - 1
    hypot2 = x*x   y*y
    c = (a b) * (a-b)
    def complex(real, imag=0.0):
        return magic(r=real, i=imag)
    def munge(input: AnyStr): ...
    def munge() -> AnyStr: ...
    def munge(sep: AnyStr = None): ...
    def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...
    if foo == 'blah':
        do_blah_thing()
    do_one()
    do_two()
    do_three()
   
   # 不推荐做法
    i=i 1
    submitted  =1
    x = x * 2 - 1
    hypot2 = x * x   y * y
    c = (a   b) * (a - b)
    def complex(real, imag = 0.0):
        return magic(r = real, i = imag)
    def munge(input:AnyStr): ...
    def munge()->PosInt: ...
    def munge(input: AnyStr=None): ...
    def munge(input: AnyStr, limit = 1000): ...
    if foo == 'blah': do_blah_thing()
    do_one(); do_two(); do_three()
```
   
# 四、注释

## 4.1 注释说明：

* 与代码相矛盾的注释比没有注释更糟糕，当代码更改时，优先更新对应的注释
   * 注释应该是完整的句子，如果一个注释是一个短语或句子，它的第一个单词应该大写
   * 注释中永远不要改变标识符的大小写
   * 如果注释很短，结尾的句号可以省略
   * 块注释一般由完整句子的一个或者多个段落组成，并且每句话结束有个句号
   * 在句尾结束的时候应该使用两个空格
   * 在非英语国家的python程序员，请使用英语写注释，除非120%的确定你的代码不会被其他语言的人阅读
   
## 4.2 块注释

* 块注释通常适用于跟随他们的某一些（或全部）代码，并缩进到代码相同的级别
   * 块注释的每一行开头使用一个#和一个空格（除非注释内部缩进文本）
   * 块注释内部的段落通过只有一个#的空行分隔
   
## 4.3 行注释

* 有节制的使用行注释
   * 行注释是与代码同行的注释，行注释和代码之间至少两个空格分隔
   * 行注释由一个#和一个空格开始
   
## 4.4 文档注释

* 要为所有的公共模块、函数、类以及方法编写文档说明，非公共的方法没有必要，但是应该有一个描述方法具体作用的注释，这个注释在def那一行之后
   * 多行文档注释的结尾的三个引号需要独自成一行
   * 对于单行的文档注释，结尾的三个引号应该和文档在一行
   
# 五、命名规范

## 5.1 最重要的原则

* 暴露给用户的api接口的命名，应该遵循反映使用场景而不是实现的原则
   
## 5.2 命名风格

* lower_case_with_underscores 使用下划线分割的小写字母
   * CapitalizadWords 驼峰命名法
   * mixedCase 第一个单词的首字母小写
   * lowercase 小写字母
   * UPPERCASE 大写字母
   * UPPER_CASE_WITH_UNDERSCORES 使用下划线分割的大写字母
   * b 单个小写字母
   * B 单个大写字母
   * Capitalized_Words_With_Underscores（巨丑）
   
## 5.3 命名约定

### 5.3.1 应避免的命名

* 永远不要使用实木'l'（小写的L），‘O’（大写的o）或者I（大写的i）作为单字符变量名

### 5.3.2 包和模块命名

* 模块名应该用简短全小写的名字，如果为了提升可读性，下划线也是可以的
* 包名也应该使用简短全小写的名字，不建议使用下划线
      
### 5.3.3 类命名

* 类名一般使用首字母大写的约定
	  
### 5.3.4 异常命名

* 异常一般都是类，所以使用类名约定，此外需要在异常名后加上‘Error’后缀

### 5.3.5 全局变量命名

* 全局变量名应该小写，如果为了提高可读性，可以使用下划线
	  
### 5.3.6 函数名命名

* 函数名应该小写，如果为了提高可读性，可以使用下划线
	  
### 5.3.7 函数和方法的参数命名
   
* 和普通的变量名一致，即小写，如果为了提高可读性，可以使用下划线
	  
### 5.3.8 方法名和实例变量命名
   
* 方法名和函数名一致，可以使用下划线
* 非公有方法名以单下划线开头
* 实例变量使用单下划线开头
	  
### 5.3.9 常量命名
   
* 通过下划线分割的全大写字母，如 MAX_OVERFLOW
	  
### 5.3.10 继承设计
   
   * 公共属性不应该有前缀下划线
   * 如果不确定一个属性时公有还是非公有，选择非公有，因为非公有转换为公有比
   反过来简单的多
   * 对于单一的公有属性数据，最好直接暴露它的变量名
   * 不希望子类使用的属性，使用双下划线开头
	  
## 5.4 公共和内部接口

* 为了更好的支持自省，模块应该使用__all__，属性显式的在他们的公共API中声明
   * 即使通过__all__设置过，内部接口（包，模块，类，方法，属性或其他名字）依然需要单个下划线前缀

# 六、编码建议

* 代码应该用不损害其他Python实现的方式编写
* 和像None这样的单例对象进行比较的时候应该使用is 或者is not ，永远不要使用等号运算符
* 始终使用def表达式，而不是通过赋值语句将lambda表达式绑定到一个变量上
* 从Exception继承异常，而不是BaseException，直接继承BaseException的异常适用于几乎不用来捕捉的异常
* 返回的语句保持一致
* 当代码片段局部使用了某个资源的时候，使用with 表达式来确保这个资源使用完后被清理干净
* 使用 ”.startswith() 和 ”.endswith() 代替通过字符串切割的方法去检查前缀和后缀
* 对象类型的比较应该用isinstance()而不是直接比较type
* 不要用 == 去和True或者False比较

```pytyon
# 推荐：
if foo is not None:
def f(x): return 2*x

# 不推荐：
if not foo is None:
f = lambda x: 2*x
```

测试开发技术网站

博客