Python代码规范！详细说明！-CSDN博客

# 函数定义，函数使用同理
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.

需要避免的名称

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

计数器和迭代器 (例如, 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 行, 应该考虑在不破坏程序结构的前提下拆分这个函数.

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

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

总结

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