XuehangCang/EasyPL-1B
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity
Files
main
EasyPL-1B/易语言风格 Python 编码规范 SKILL.md
ModelHub XC 81e7754a4b 初始化项目，由ModelHub XC社区提供模型 
Model: XuehangCang/EasyPL-1B
Source: Original Platform
2026-07-21 22:28:29 +08:00

9.9 KiB
Raw Permalink Blame History

易语言风格 Python 编码规范

目标

本规范用于约束一种“易语言风格”的 Python 编码方式：用中文表达程序意图，用接近自然语言的函数名、变量名和注释降低阅读门槛，同时遵守 Python 语法、PEP8 格式和基本工程质量要求。

这种风格不是简单把英文 API 翻译成中文，而是让代码像中文命令一样直接表达“做什么”。

核心目标：

  • 代码可运行，符合 Python 语法
  • 命名中文化，语义清晰
  • 函数职责单一，像“命令”一样可组合
  • 注释解释意图和边界，不重复代码
  • 格式遵循 PEP8，便于工具格式化和维护
  • 尽量使用标准库实现通用能力

总体风格

易语言风格代码强调“读代码像读中文说明”。

推荐：

import uuid


def 取UUID() -> str:
    """生成一个随机 UUID（文本形式）。"""
    return str(uuid.uuid4())

不推荐：

def get_uuid():
    return uuid.uuid4()

如果代码主要服务中文风格训练或中文使用者，优先使用中文命名；如果必须调用第三方库或系统 API，保留原始英文 API 名称，只在自定义封装层使用中文命名。

命名规范

函数命名

函数名应表达一个明确动作，通常采用“动词 + 对象”结构。

推荐形式：

  • 取UUID
  • 取时间戳
  • 生成随机字符串
  • 读取JSON文件
  • 写入文本文件
  • 计算MD5
  • 文本_取左边
  • 文本_取右边
  • 文本_取中间
  • 文件_是否存在
  • 路径_拼接
  • 异常_转中文提示

常用动词约定：

  • 取：获取已有值或即时计算值，如 取时间戳
  • 生成：创建新值，如 生成随机字符串
  • 读取：从文件、网络、配置中取数据，如 读取JSON文件
  • 写入：把数据保存到外部位置，如 写入文本文件
  • 转换 / 到：类型转换，如 文本到字节集
  • 判断 / 是否：返回布尔值，如 文件_是否存在
  • 计算：摘要、统计、数值结果，如 计算SHA256
  • 删除：移除内容，如 文本_删左边
  • 查找 / 寻找：定位内容，如 寻找文本

变量命名

变量名应使用中文名词或名词短语，表达数据含义。

推荐：

文件路径 = "config.json"
文本内容 = "你好世界"
哈希对象 = hashlib.md5()
当前时间 = datetime.datetime.now()
随机文本 = 生成随机字符串(16)

避免：

a = "config.json"
txt = "你好世界"
hash_obj = hashlib.md5()

允许在非常局部的循环中使用短变量，但更推荐中文语义变量：

for 序号, 项目 in enumerate(项目列表, start=1):
    print(序号, 项目)

类命名

类名使用中文名词，表达对象或工具集合。

推荐：

  • 文本工具
  • 文件工具
  • 配置读取器
  • 异常处理器
  • 日期时间工具

类中方法仍使用动词结构：

class 文本工具:
    def 取左边(self, 文本: str, 长度: int) -> str:
        return 文本[:长度]

常量命名

常量使用清晰中文名，优先保持统一。

默认编码 = "utf-8"
最大重试次数 = 3
请求超时时间 = 10

如果项目已有英文大写常量风格，可以保留：

DEFAULT_ENCODING = "utf-8"

模块组织

一个文件应围绕一个主题组织。

推荐模块主题：

  • 文本操作
  • 文件操作
  • 路径操作
  • 编码解码
  • JSON 操作
  • 时间日期
  • 哈希摘要
  • 随机数据
  • 异常处理
  • 网络请求
  • 配置读取

文件内部推荐顺序：

  1. 标准库导入
  2. 第三方库导入
  3. 常量定义
  4. 工具函数
  5. 类定义
  6. if __name__ == "__main__": 示例或测试入口

示例：

import json
from pathlib import Path


默认编码 = "utf-8"


def 读取JSON文件(文件路径: str):
    """读取 JSON 文件并返回解析后的对象。"""
    with open(文件路径, "r", encoding=默认编码) as 文件对象:
        return json.load(文件对象)


def 写入JSON文件(文件路径: str, 数据) -> None:
    """将对象写入 JSON 文件。"""
    Path(文件路径).parent.mkdir(parents=True, exist_ok=True)
    with open(文件路径, "w", encoding=默认编码) as 文件对象:
        json.dump(数据, 文件对象, ensure_ascii=False, indent=4)

函数设计规范

函数应短小、明确、可复用。

要求：

  • 一个函数只做一件事
  • 函数名能说明用途
  • 参数名使用中文，必要时加类型注解
  • 返回值类型尽量稳定
  • 不在工具函数里随意 print，除非函数职责就是输出
  • 不在函数里吞掉异常后返回含糊结果，除非函数名明确表达“安全”或“尝试”

推荐：

def 文本_取左边(文本: str, 长度: int) -> str:
    """从左侧取指定长度的文本。"""
    if 长度 <= 0:
        return ""
    return 文本[:长度]

不推荐：

def 处理(a, b):
    print(a[:b])

注释和文档字符串

注释使用中文，解释“为什么这样做”或“边界条件”，不要重复代码本身。

推荐 docstring：

import hashlib


def 计算MD5(文本内容: str) -> str:
    """计算文本内容的 MD5 十六进制摘要。"""
    哈希对象 = hashlib.md5()
    哈希对象.update(文本内容.encode("utf-8"))
    return 哈希对象.hexdigest()

复杂函数可以写参数说明：

def 生成随机字符串(长度: int, 包含数字: bool = True) -> str:
    """
    生成指定长度的随机字符串。

    参数:
        长度: 生成字符串的字符数量。
        包含数字: 是否允许结果中出现数字。
    """

避免无意义注释：

# 返回结果
return 结果

异常处理规范

默认让异常自然抛出，除非有明确的中文化、重试、默认值需求。

推荐显式异常：

def 读取文本文件(文件路径: str, 编码: str = "utf-8") -> str:
    """读取文本文件内容。"""
    with open(文件路径, "r", encoding=编码) as 文件对象:
        return 文件对象.read()

需要安全返回时，函数名要说明行为：

def 尝试读取文本文件(文件路径: str, 默认值: str = "") -> str:
    """读取文本文件，失败时返回默认值。"""
    try:
        with open(文件路径, "r", encoding="utf-8") as 文件对象:
            return 文件对象.read()
    except OSError:
        return 默认值

异常中文化函数应单独封装：

def 异常_转中文提示(异常对象: Exception) -> str:
    """把常见 Python 异常转换为中文提示。"""
    异常类型 = type(异常对象).__name__
    原始信息 = str(异常对象)
    return f"{异常类型}：{原始信息}"

PEP8 格式规范

易语言风格只改变命名表达，不改变 Python 的格式底线。代码必须遵守 PEP8。

要求：

  • 使用 4 个空格缩进
  • 顶层函数、类之间空 2 行
  • 类方法之间空 1 行
  • import 放在文件顶部
  • 标准库、第三方库、本地库分组导入
  • 行宽尽量控制在 88 到 100 个字符
  • 运算符两侧保留空格
  • 逗号后保留一个空格
  • 函数默认参数写作 参数: 类型 = 默认值
  • 文件末尾保留一个换行
  • 优先使用 ruff format 或 black 格式化

推荐：

import hashlib


def 计算SHA256(文本内容: str) -> str:
    """计算文本内容的 SHA256 摘要。"""
    哈希对象 = hashlib.sha256()
    哈希对象.update(文本内容.encode("utf-8"))
    return 哈希对象.hexdigest()

不推荐：

import hashlib

def 计算SHA256(文本内容):
  哈希对象=hashlib.sha256();哈希对象.update(文本内容.encode('utf-8'));return 哈希对象.hexdigest()

常用代码模板

UUID

import uuid


def 取UUID() -> str:
    """生成随机 UUID 字符串。"""
    return str(uuid.uuid4())

时间戳

import time


def 取时间戳(毫秒: bool = False) -> int:
    """获取当前时间戳。"""
    当前时间 = time.time()
    if 毫秒:
        return int(当前时间 * 1000)
    return int(当前时间)

文本截取

def 文本_取中间(文本: str, 左标记: str, 右标记: str) -> str:
    """提取两个标记之间的文本。"""
    左位置 = 文本.find(左标记)
    if 左位置 == -1:
        return ""

    开始位置 = 左位置 + len(左标记)
    右位置 = 文本.find(右标记, 开始位置)
    if 右位置 == -1:
        return ""

    return 文本[开始位置:右位置]

JSON 文件

import json


def 读取JSON文件(文件路径: str):
    """读取 JSON 文件并返回 Python 对象。"""
    with open(文件路径, "r", encoding="utf-8") as 文件对象:
        return json.load(文件对象)


def 写入JSON文件(文件路径: str, 数据) -> None:
    """把 Python 对象写入 JSON 文件。"""
    with open(文件路径, "w", encoding="utf-8") as 文件对象:
        json.dump(数据, 文件对象, ensure_ascii=False, indent=4)

禁止事项

  • 不要为了中文化牺牲 Python 语法正确性
  • 不要使用拼音代替中文命名
  • 不要把多个无关能力塞进一个函数
  • 不要在工具函数中随意打印调试信息
  • 不要保留明显错误的示例代码
  • 不要生成无法通过 ast.parse 的代码
  • 不要把第三方项目名写进通用风格规范
  • 不要使用 from xxx import * 作为通用模板

质量检查清单

提交或生成代码前检查：

  • 函数名是否中文且能表达用途
  • 变量名是否清楚表达数据含义
  • 函数是否只做一件事
  • 是否使用标准库优先实现
  • 是否有必要的中文 docstring
  • 是否遵守 PEP8 缩进和空行
  • 是否通过格式化工具
  • 是否通过 Python 语法检查
  • 是否去除了无意义打印和临时代码
  • 是否没有依赖特定项目内部路径

风格一句话

用中文命名表达意图，用 Python 语法保证正确，用 PEP8 格式保证可维护。