「Python编程规范」为Python代码添加注释

Posted 2023-03-22

参考技术A

功能要求

为Python代码添加注释，对Python程序代码进行说明。

实例代码

\'\'\'多行注释开始

下面的代码根据变量x的值计算y

注意代码中使用缩进表示代码块

多行注释结束\'\'\'

x = 5

if x > 100:

y = x * 5 - 1 # 单行注释：x>100时执行该语句

else:

y = 0 # x <= 100时执行该语句

print(y) # 输出y

运行结果

知识说明

注释用于为程序添加说明性的文字，帮助程序员更好的阅读和理解程序代码。Python解释器会忽略注释的内容，即注释的内容不会被Python解释器执行。

Python注释分为单行注释和多行注释。

单行注释以符号“#”开始，当前行中符号“#”及其后的内容为注释语句。单行注释可以独占一行，也可放在语句末尾。 说明： 在Pycharm中使用“ctrl + /”可以添加/取消单行注释。

多行注释是用3个英文单引号“\'\'\'多行注释文本\'\'\'”或3个双引号“"""注释文本"""”进行注释。 注意： 由一对三个单引号或一对三个双引号括起来的内容被认为是注释，但不能由三个单引号和三个双引号混合使用。

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

---

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

---