python3代码编程规范(命名空格注释代码布局编程建议等)

Posted cui_yonghua

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了python3代码编程规范(命名空格注释代码布局编程建议等)相关的知识,希望对你有一定的参考价值。


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

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:
...

以上是关于python3代码编程规范(命名空格注释代码布局编程建议等)的主要内容,如果未能解决你的问题,请参考以下文章

Python 常用PEP8规范

代码规范

代码精进之路——如何写好代码

JavaScript 代码规范

微软编程规范(文档)

css规范与模块化