Python代码规范！详细说明！

背景

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

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

于是打算针对市面上常见的代码规范进行强调，结果在查看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 andcolor == '红' 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__方法以外的地方声明定义！

针对类变量和实例变量的解释如下：

在python当中，类内定义的属性，有self和没有self有什么区别？-CSDN博客

类变量在类文档字符串下方申明

类内实例变量在Init函数内申明

需要提前初始化的内容。
需要在类初始化的时候返回给用户的说明

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

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

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

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

一个例子如下：

class Math:'''用以进行数学计算涵盖的方法有：add公有属性说明：name：名称method：方法名'''__init__(name = "name", method = "method"):'''初始化类'''self.name = nameself.method = methodadd(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.

需要避免的名称

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

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

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

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

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

首尾均为双下划线的名称, 例如 __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 行, 应该考虑在不破坏程序结构的前提下拆分这个函数.

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

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

总结

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

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. 函数长度

总结

相关资讯

热文排行

最新新闻

推荐新闻

热搜词