python3代码编程规范（命名、空格、注释、代码布局、编程建议等）

ゝ一世哀愁。 2022-10-16 08:50 189阅读 0赞

--------------------

在日常工作中，编写python代码时，大家有可能因为IDE的不同或者是没有遵循python的pep8规范而导致每个人的格式都不尽相同，导致其他人阅读起来比较吃力。但是有时候代码规范也并不是建议使用的，最主要的是**风格一致性**，每个组内的代码风格统一起来才是最重要的，根据自己的判断选择是否遵循PEP8。

*  PEP8 规范链接： [官方链接][Link 1]、[中文翻译][Link 2]

**ps: 许多项目有自己的编码规范，在出现规范冲突时，项目自身的规范优先。**

接下来我们只挑一些在工作中频繁遇到规范进行示例，为减少大家阅读时间，以 **推荐** 和 **糟糕** 来说明。

## 一. **命名规范** ##

命名规范很重要，很多时候你的命名能够大致的解释了变量、函数、类是用来做什么的。所以在命名的时候一定要选择贴近的词义，让阅读者可以理解

#### 1.1 **包名和模块名** ####

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

#### 1.2 **类名** ####

类名一般使用单词首字母大写的约定

**推荐:**

class CheckFunc:...

**糟糕:**

# 首字符需大写，同时类名中无需带下划线
    class check_func:...
    
    
    # 全部大写，同时类名中无需带下划线
    class CHECK_FUNC:...

#### 1.3 **函数名** ####

函数名应该小写，如果想提高可读性可以用下划线分隔。

**推荐:**

def check_func():...

#### 1.4 **变量名** ####

一定要靠近变量的意思，不要使用一些意义不明的参数，如：i，j，k，特别注意永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。

**糟糕:**

l = []
    
    i = 0
    
    xxx = [for i in xx]

#### 1.5 **常量** ####

常量一般默认全部为大写, 同时一定要表明好注释

**推荐:**

TOTAL = 10  # 订单总页数
    
    # 最大溢出量
    MAX_OVERFLOW = 1000

#### 1.6 **异常名** ####

因为异常一般都是类，所有类的命名方法在这里也适用。

**推荐:**

class ErrorInvalidArgument(ApiError):
        """ 参数缺失或错误 """
        code = 401001
        code_name = 'Invalid_Argument'
        message = 'invalid argument.'
        zh_message = '参数缺失或错误'

## 二. **表达式和语句中的空格** ##

#### 2.1 **二元运算符中的空格：** ####

**推荐:**

i = i + 1
    
    submitted += 1
    
    x = x*2 - 1
    
    hypot2 = x*x + y*y
    
    c = (a+b) * (a-b)

**糟糕:**

i=i+1
    
    submitted +=1
    
    x = x * 2 - 1
    
    hypot2 = x * x + y * y
    
    c = (a + b) * (a - b)

#### 2.2 **关键字参数或者默认参数值：** ####

**推荐:**

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

**糟糕:**

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

## 三. **注释** ##

当更新代码时，一定要记得同步更新注释，否则使阅读的人会陷入更糟糕的近况。

#### 3.1 **文档字符串** ####

**推荐:**

"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """

#### 3.2 **函数或方法注释** ####

大家在写函数或者方法时，往往会漏掉当前方法或函数的作用，其实这个还是很重要的，这样往往不需要阅读你的逻辑就可以知道你准备干什么

**推荐:**

""" def oa_notice_template(project, api, account, cpu, mem): """
        压测申请模板
        :param project: 项目名称
        :param api: 接口名称
        :param account: 申请人
        :param cpu: cpu核数
        :param mem: 内存大小
        :return:
        """ """

#### 3.3 **其他建议** ####

在编写代码时，阅读者追寻编写人时往往很困难，或者此文件具体是做什么的。这个时候我们稍微添加一些个人信息注释就很好做到追源了。

**推荐:**

""" @Description: 接口测试上传 @Author : xxx @Time : 2021/5/9 11:51 下午 @Site : @File : http_test_xpa.py """
    
    import os
    ...

## 四. **代码布局** ##

#### 4.1 **缩进** ####

每一级缩进使用4个空格。

推荐:

# 与左括号对齐
    foo = long_function_name(var_one, var_two,
                             var_three, var_four)
                             
    # 用更多的缩进来与其他行区分
    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)
    
    # 与内容对齐
    my_list = [
        1, 2, 3,
        4, 5, 6,
        ]
    
    # 与第一行第一个字符对齐
    my_list = [
        1, 2, 3,
        4, 5, 6,
    ]

**糟糕:**

# 没有使用垂直对齐时，禁止把参数放在第一行
    foo = long_function_name(var_one, var_two,
        var_three, var_four)
    
    # 当缩进没有与其他行区分时，要增加缩进
    def long_function_name(
        var_one, var_two, var_three,
        var_four):
        print(var_one)
    
    my_list = [1, 2, 3, 4, 5, 6]

#### 4.2 **行的最大长度** ####

**所有行限制的最大字符数为79。**

#### 4.3 **空行** ####

**推荐:**

# 类与类之间前后用两个空行隔开
    Class A:...
    
    
    Class B:...
    
    
    # 类中函数与函数之间前后用一个空行隔开
    Class C:
        def c_a(self):...
        
        def c_b(self):...
    
    
    # 函数与函数之间前后用两个空行隔开
    def a_run():...
    
    
    def b_run():...
    
    
    # 在函数中使用空行来区分逻辑段（谨慎使用）。
    def c_run():
        # 逻辑A
        ...
        ...
        
        # 逻辑B
        ...
        ...

#### 4.4 **导入** ####

**推荐:**

*  导入应该按照以下顺序分组：
    
     *  标准库导入
     *  相关第三方库导入
     *  本地应用/库特定导入

同时在每一组导入之间加入空行。

# 官方标准库导入
    import os
    import sys
    
    # 第三方库
    import arrow
    import requests
    
    # 导入本地库
    import app
    
    # 以from导入标准库
    from datetime import datetime
    
    # 以from导入第三方库
    from ldap3 import Server
    
    # 以from导入本地库
    from app import DB
    from . import create_app  # 处理绝对路径过长时可以以相对路径进行替换

**糟糕:**

# 在import中导入多个库
    import sys, os

## 五. **python编程建议** ##

#### 5.1 **关于异常处理：** ####

**推荐:**

try:
        value = collection[key]
    except KeyError:
        return key_not_found(key)
    else:
        return handle_value(value)

**糟糕:**

try:
        return handle_value(collection[key])
    except KeyError:
        return key_not_found(key)

#### 5.2 **关于返回结果处理：** ####

不管在任何时候返回结果都需要保持一致。

**推荐:**

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

**糟糕:**

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

#### 5.3 **关于True、Fakse的判断：** ####

不要用 == 去和True或者False比较

**推荐:**

if greeting:
    ...

**糟糕:**

if greeting == True:
    ...
    
    if greeting is True:
    ...

--------------------

[Link 1]: https://pep8.org/
[Link 2]: https://www.cnblogs.com/bymo/p/9567140.html