背景

最近在协作开发过程中，遇到了诸多问题。总结下来主要有两点大问题

• 代码风格不统一，代码习惯问题严峻。
• 系统解耦不清晰，信息传输不清晰。

于是打算针对市面上常见的代码规范进行强调，结果在查看Google python代码规范文档的时候发现自己对于有些代码规范也不清楚，不由感到有些汗颜。

于是在此编写下Python代码规范，以供读者和自己参考。本文将针对Python代码规范进行解释，对于规则的原因和由来进行说明，对于规则本身可以根据实际情况进行裁剪，选择最适用自己的python代码规范。

目录

背景

一、Python 代码风格规范

1. 分号

2. 行宽

3. 续行

4. 括号

5. 缩进 

6. 注释和文档字符串 (docstring)

6.1 文档字符串

6.2 类的注释

6.3 块注释和行注释

7. 类 (class)

7.1 类的__init__方法

7.2 类的文档字符串注释说明

 8. 字符串

 9. 命名

10. 主程序 

11. 函数长度

总结

---

一、Python 代码风格规范

1. 分号

Python代码规范中，禁止在行末尾使用分号！虽然python解释器并不会报错，运行也没有问题。

分号是C++和JAVA语言常用的符号，用以标明代码行的结束。但在Python中，无需此操作，python一般情况下默认通过代码末尾的换行符来表示结束。

至于禁止使用的原因，则是会产生混淆以及增加代码风格的差异，对于任何Python开发都应该遵顼此标准，请不要使用分号 “；”

2. 行宽

在Python代码规范中，每一行的行宽不要超过80个字符（包括缩进） 。过长的行宽，需要使用续行的方式分两行写。

当然也有一些例外：

• 长的导入 (import) 语句.
• 注释里的 URL、路径名以及长的标志 (flag).
• 不便于换行、不包含空格、模块级的长字符串常量, 比如 URL 或路径名.

该标准主要是为阅读方便，降低阅读难度。

若不做限制，我亲眼见过有人在 if 语句里面塞了 10个“==” 和“and”来判断……

3. 续行

 不使用显式续行、使用隐式续行！

对于显示续行和隐式续行，请查阅下方内容。

对于续航的代码，下面为正确与错误的对比。

正确使用方式：

# 函数定义，函数使用同理
def function(width, height, color='黑', design=None, x='foo',
        emphasis=None, highlight=0)

# 表达式使用
if (width == 0 and height == 0 and
    color == '红' and emphasis == '加粗'):

# 过长目录下的变量定义
(bridge_questions.clarification_on
 .average_airspeed_of.unladen_swallow) = '美国的还是欧洲的?'

# python关键字使用
with (
    very_long_first_expression_function() as spam,
    very_long_second_expression_function() as beans,
    third_thing() as eggs,
):
    place_order(eggs, beans, spam, beans)

# 长字符串定义
x = ('这是一个很长很长很长很长很长很长'
     '很长很长很长很长很长的字符串')

错误使用方式：

if width == 0 and height == 0 and \
    color == '红' and emphasis == '加粗':

bridge_questions.clarification_on \
    .average_airspeed_of.unladen_swallow = '美国的还是欧洲的?'

with very_long_first_expression_function() as spam, \
        very_long_second_expression_function() as beans, \
        third_thing() as eggs:
    place_order(eggs, beans, spam, beans)

注意：必要时, 注释中的长 URL 可以独立成行.

4. 括号

尽可能少的使用括号！

依旧是为了代码的可读性考虑。C++和JAVA就是因为滥用（）使得代码可读性上远远不如Python。 

 代码对比：

正确：

# 表达式相关
if True:
    function()

while x:
    x = function()

if x and y:
    function()

if not x:
    function()

# 对于包含单个元素的元组, 括号比逗号更直观.
onesie = (foo,)

# 返回值相关
return foo
return spam, beans
return (spam, beans)

for (x, y) in dict.items(): ...

错误：

if (x):
    bar()
if not(x):
    bar()
return (foo)

总而言之，在Python中，尽可能减少（）使用

5. 缩进 

用4个空格作为缩进.Tab缩进需要设定为4个空格缩进，禁止使用制表符！

使用续行时, 应该把括起来的元素垂直对齐, 或者添加4个空格的悬挂缩进. 右括号 (圆括号, 方括号或花括号) 可以置于表达式结尾或者另起一行. 另起一行时右括号应该和左括号所在的那一行缩进相同.

代码示例：

正确：

# 与左括号对齐.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
meal = (spam,
        beans)

# 与字典的左括号对齐.
foo = {
    'long_dictionary_key': value1 +
                           value2,
    ...
}

# 4个空格的悬挂缩进; 首行没有元素
foo = long_function_name(
    var_one, var_two, var_three,
    var_four)
meal = (
    spam,
    beans)

# 4个空格的悬挂缩进; 首行没有元素
# 右括号另起一行.
foo = long_function_name(
    var_one, var_two, var_three,
    var_four
)
meal = (
    spam,
    beans,
)

# 字典中的4空格悬挂缩进.
foo = {
    'long_dictionary_key':
        long_dictionary_value,
    ...
}

错误：

# 未垂直对齐
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# 禁止2个空格的悬挂缩进.
foo = long_function_name(
  var_one, var_two, var_three,
  var_four)

# 字典没有悬挂缩进.
foo = {
    'long_dictionary_key':
    long_dictionary_value,
    ...
}

6. 注释和文档字符串 (docstring)

6.1 文档字符串

Python 的文档字符串用于注释代码. 文档字符串是包、模块、类或函数里作为第一个语句的字符串. 可以用对象的 __doc__ 成员自动提取这些字符串。文档字符串一定要用三重双引号 """ 的格式。

对于单行文档字符串，需要对函数功能进行描述。

例如：

def add(a, b):
    ''' 对输入的参数求和，并返回和'''
    return a + b

对于多行字符串，要求如下：

• 第一行描述函数功能
• 第二行空行
• 第三部分描述函数的输入参数要求
• 第四部分描述返回值
• 第五部分给出本函数的使用样例（可选）

以下是样例：

def add(a, b):
    ''' 
    对输入的参数求和，并返回和
    
    参数：
        a：int 型，需要求和的其中一个值
        b：int 型，需要求和的另外一个值
    
    返回值：int 型，返回的求和的值

    函数使用样例：
    sum = add(1, 5)
    '''
    return a + b

 注意：函数内若有错误抛出，也需要在文本字符串中显示

6.2 类的注释

详见 第7节

6.3 块注释和行注释

 最后一种需要写注释的地方是代码中复杂的部分. 如果你可能在以后 代码评审 (code review) 时要解释某段代码, 那么现在就应该给这段代码加上注释. 应该在复杂的操作开始前写上若干行注释. 对于不是一目了然的代码, 应该在行尾添加注释.

为了提高可读性, 注释的井号和代码之间应有至少2个空格, 井号和注释之间应该至少有一个空格.

除此之外, 绝不要仅仅描述代码. 应该假设读代码的人比你更懂Python, 只是不知道你的代码要做什么.

# 不好的注释: 现在遍历数组 b, 确保每次 i 出现时, 下一个元素是 i+1

7. 类 (class)

对于python中类的定义，和其他语言基本保持一致。

要求如下：

7.1 类的__init__方法

所有的类必须重写__init__方法，就算你没有额外的操作，也请重写__init__方法。

__init__方法应该包含的内容：

• 所有的类内变量，禁止类内变量在__init__方法以外的地方声明定义！
• 需要提前初始化的内容。
• 需要在类初始化的时候返回给用户的说明

7.2 类的文档字符串注释说明

类也是有文档字符串的。类的文档字符串定义和函数相似，但有些许不同。规范如下：

类的文档字符串最好使用多行注释！需要涵盖的内容如下：

• 第一行：类的概括性描述
• 第二部分：类的详细说明和其他可能的相关描述
• 第三部分：类内公有属性的说明

一个例子如下：

class Math:
    '''
    用以进行数学计算

    涵盖的方法有：add
    
    公有属性说明：
        name：名称
        method：方法名
    '''
    __init__(name = "name", method = "method"):
        '''初始化类'''
        self.name = name
        self.method = method

    add(self, x, y):
        ''' add x and y together'''
        return x + y

 8. 字符串

不要在循环中用 + 和 += 操作符来堆积字符串. 这有时会产生平方而不是线性的时间复杂度. 有时 CPython 会优化这种情况, 但这是一种实现细节. 我们无法轻易预测这种优化是否生效, 而且未来情况可能出现变化. 作为替代方案, 你可以将每个子串加入列表, 然后在循环结束后用 ''.join 拼接列表. 也可以将每个子串写入一个 io.StringIO 缓冲区中. 这些技巧保证始终有线性的平摊 (amortized) 时间复杂度.

正确:

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)

 9. 命名

函数名、变量名和文件名应该是描述性的, 避免缩写. 特别要避免那些对于项目之外的人有歧义或不熟悉的缩写, 也不要通过省略单词中的字母来进行缩写.

• 模块名: module_name;
• 包名: package_name;
• 类名: ClassName;
• 方法名: method_name;
• 异常名: ExceptionName;
• 函数名: function_name, query_proper_noun_for_thing, send_acronym_via_https;
• 全局常量名: GLOBAL_CONSTANT_NAME ;
• 全局变量名: global_var_name;
• 实例名: instance_var_name;
• 函数参数名: function_parameter_name;
• 局部变量名: local_var_name.

需要避免的名称

1. 只有单个字符的名称, 除了以下特别批准的情况:

   1. 计数器和迭代器 (例如, i, j, k, v 等等).

   2. 在 try/except 语句中代表异常的 e.

   3. 在 with 语句中代表文件句柄的 f.

2. 包含连字符(-) 的包名/模块名.

3. 首尾均为双下划线的名称, 例如 __double_leading_and_trailing_underscore__ (此类名称是 Python 的保留名称).

例子：

类型	公有	内部
包	lower_with_under
模块	lower_with_under	_lower_with_under
类	CapWords	_CapWords
异常	CapWords
函数	lower_with_under()	_lower_with_under()
全局常量/类常量	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
全局变量/类变量	lower_with_under	_lower_with_under
实例变量	lower_with_under	_lower_with_under
方法名	lower_with_under()	_lower_with_under()
函数参数/方法参数	lower_with_under
局部变量	lower_with_under

 

数学符号

对于涉及大量数学内容的代码, 如果相关论文或算法中有对应的符号, 则可以忽略以上命名规范并使用较短的变量名. 若要采用这种方法, 应该在注释或者文档字符串中注明你所使用的命名规范的来源. 如果原文无法访问, 则应该在文档中清楚地记录命名规范. 建议公开的 API 使用符合 PEP8 的、描述性的名称, 因为使用 API 的代码很可能缺少相关的上下文信息.

10. 主程序 

 统一使用下面的格式：

def main():
    ...

if __name__ == '__main__':
    
    main()

 if __name__ == '__main__':

此部分内容需要包含所有的全局变量的申明定义，以及main函数的执行。

def main():

此部分需要包含所有高层次的代码步骤，尽可能保持精简。

要求为：阅读者仅需要通过阅读main函数，就可以知道你整个模块系统的大概内容。

11. 函数长度

我们承认有时长函数也是合理的, 所以不硬性限制函数长度. 若一个函数超过 40 行, 应该考虑在不破坏程序结构的前提下拆分这个函数.

即使一个长函数现在没有问题, 几个月后可能会有别人添加新的效果. 此时容易出现隐蔽的错误. 保持函数简练, 这样便于别人阅读并修改你的代码.

当你使用某些代码时, 可能发现一些冗长且复杂的函数. 要勇于修改现有的代码: 如果该函数难以使用或者存在难以调试的错误, 亦或是你想在不同场景下使用该函数的片段, 不妨考虑把函数拆分成更小、更容易管理的片段.

总结

综上，是一些常用的代码风格规范说明。