423 lines
9.9 KiB
Markdown
423 lines
9.9 KiB
Markdown
# 易语言风格 Python 编码规范
|
||
|
||
## 目标
|
||
|
||
本规范用于约束一种“易语言风格”的 Python 编码方式：用中文表达程序意图，用接近自然语言的函数名、变量名和注释降低阅读门槛，同时遵守 Python 语法、PEP8 格式和基本工程质量要求。
|
||
|
||
这种风格不是简单把英文 API 翻译成中文，而是让代码像中文命令一样直接表达“做什么”。
|
||
|
||
核心目标：
|
||
|
||
- 代码可运行，符合 Python 语法
|
||
- 命名中文化，语义清晰
|
||
- 函数职责单一，像“命令”一样可组合
|
||
- 注释解释意图和边界，不重复代码
|
||
- 格式遵循 PEP8，便于工具格式化和维护
|
||
- 尽量使用标准库实现通用能力
|
||
|
||
## 总体风格
|
||
|
||
易语言风格代码强调“读代码像读中文说明”。
|
||
|
||
推荐：
|
||
|
||
```python
|
||
import uuid
|
||
|
||
|
||
def 取UUID() -> str:
|
||
"""生成一个随机 UUID（文本形式）。"""
|
||
return str(uuid.uuid4())
|
||
```
|
||
|
||
不推荐：
|
||
|
||
```python
|
||
def get_uuid():
|
||
return uuid.uuid4()
|
||
```
|
||
|
||
如果代码主要服务中文风格训练或中文使用者，优先使用中文命名；如果必须调用第三方库或系统 API，保留原始英文 API 名称，只在自定义封装层使用中文命名。
|
||
|
||
## 命名规范
|
||
|
||
### 函数命名
|
||
|
||
函数名应表达一个明确动作，通常采用“动词 + 对象”结构。
|
||
|
||
推荐形式：
|
||
|
||
- `取UUID`
|
||
- `取时间戳`
|
||
- `生成随机字符串`
|
||
- `读取JSON文件`
|
||
- `写入文本文件`
|
||
- `计算MD5`
|
||
- `文本_取左边`
|
||
- `文本_取右边`
|
||
- `文本_取中间`
|
||
- `文件_是否存在`
|
||
- `路径_拼接`
|
||
- `异常_转中文提示`
|
||
|
||
常用动词约定：
|
||
|
||
- `取`：获取已有值或即时计算值，如 `取时间戳`
|
||
- `生成`：创建新值，如 `生成随机字符串`
|
||
- `读取`：从文件、网络、配置中取数据，如 `读取JSON文件`
|
||
- `写入`：把数据保存到外部位置，如 `写入文本文件`
|
||
- `转换` / `到`：类型转换，如 `文本到字节集`
|
||
- `判断` / `是否`：返回布尔值，如 `文件_是否存在`
|
||
- `计算`：摘要、统计、数值结果，如 `计算SHA256`
|
||
- `删除`：移除内容，如 `文本_删左边`
|
||
- `查找` / `寻找`：定位内容，如 `寻找文本`
|
||
|
||
### 变量命名
|
||
|
||
变量名应使用中文名词或名词短语，表达数据含义。
|
||
|
||
推荐：
|
||
|
||
```python
|
||
文件路径 = "config.json"
|
||
文本内容 = "你好世界"
|
||
哈希对象 = hashlib.md5()
|
||
当前时间 = datetime.datetime.now()
|
||
随机文本 = 生成随机字符串(16)
|
||
```
|
||
|
||
避免：
|
||
|
||
```python
|
||
a = "config.json"
|
||
txt = "你好世界"
|
||
hash_obj = hashlib.md5()
|
||
```
|
||
|
||
允许在非常局部的循环中使用短变量，但更推荐中文语义变量：
|
||
|
||
```python
|
||
for 序号, 项目 in enumerate(项目列表, start=1):
|
||
print(序号, 项目)
|
||
```
|
||
|
||
### 类命名
|
||
|
||
类名使用中文名词，表达对象或工具集合。
|
||
|
||
推荐：
|
||
|
||
- `文本工具`
|
||
- `文件工具`
|
||
- `配置读取器`
|
||
- `异常处理器`
|
||
- `日期时间工具`
|
||
|
||
类中方法仍使用动词结构：
|
||
|
||
```python
|
||
class 文本工具:
|
||
def 取左边(self, 文本: str, 长度: int) -> str:
|
||
return 文本[:长度]
|
||
```
|
||
|
||
### 常量命名
|
||
|
||
常量使用清晰中文名，优先保持统一。
|
||
|
||
```python
|
||
默认编码 = "utf-8"
|
||
最大重试次数 = 3
|
||
请求超时时间 = 10
|
||
```
|
||
|
||
如果项目已有英文大写常量风格，可以保留：
|
||
|
||
```python
|
||
DEFAULT_ENCODING = "utf-8"
|
||
```
|
||
|
||
## 模块组织
|
||
|
||
一个文件应围绕一个主题组织。
|
||
|
||
推荐模块主题：
|
||
|
||
- 文本操作
|
||
- 文件操作
|
||
- 路径操作
|
||
- 编码解码
|
||
- JSON 操作
|
||
- 时间日期
|
||
- 哈希摘要
|
||
- 随机数据
|
||
- 异常处理
|
||
- 网络请求
|
||
- 配置读取
|
||
|
||
文件内部推荐顺序：
|
||
|
||
1. 标准库导入
|
||
2. 第三方库导入
|
||
3. 常量定义
|
||
4. 工具函数
|
||
5. 类定义
|
||
6. `if __name__ == "__main__":` 示例或测试入口
|
||
|
||
示例：
|
||
|
||
```python
|
||
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`，除非函数职责就是输出
|
||
- 不在函数里吞掉异常后返回含糊结果，除非函数名明确表达“安全”或“尝试”
|
||
|
||
推荐：
|
||
|
||
```python
|
||
def 文本_取左边(文本: str, 长度: int) -> str:
|
||
"""从左侧取指定长度的文本。"""
|
||
if 长度 <= 0:
|
||
return ""
|
||
return 文本[:长度]
|
||
```
|
||
|
||
不推荐：
|
||
|
||
```python
|
||
def 处理(a, b):
|
||
print(a[:b])
|
||
```
|
||
|
||
## 注释和文档字符串
|
||
|
||
注释使用中文，解释“为什么这样做”或“边界条件”，不要重复代码本身。
|
||
|
||
推荐 docstring：
|
||
|
||
```python
|
||
import hashlib
|
||
|
||
|
||
def 计算MD5(文本内容: str) -> str:
|
||
"""计算文本内容的 MD5 十六进制摘要。"""
|
||
哈希对象 = hashlib.md5()
|
||
哈希对象.update(文本内容.encode("utf-8"))
|
||
return 哈希对象.hexdigest()
|
||
```
|
||
|
||
复杂函数可以写参数说明：
|
||
|
||
```python
|
||
def 生成随机字符串(长度: int, 包含数字: bool = True) -> str:
|
||
"""
|
||
生成指定长度的随机字符串。
|
||
|
||
参数:
|
||
长度: 生成字符串的字符数量。
|
||
包含数字: 是否允许结果中出现数字。
|
||
"""
|
||
```
|
||
|
||
避免无意义注释：
|
||
|
||
```python
|
||
# 返回结果
|
||
return 结果
|
||
```
|
||
|
||
## 异常处理规范
|
||
|
||
默认让异常自然抛出，除非有明确的中文化、重试、默认值需求。
|
||
|
||
推荐显式异常：
|
||
|
||
```python
|
||
def 读取文本文件(文件路径: str, 编码: str = "utf-8") -> str:
|
||
"""读取文本文件内容。"""
|
||
with open(文件路径, "r", encoding=编码) as 文件对象:
|
||
return 文件对象.read()
|
||
```
|
||
|
||
需要安全返回时，函数名要说明行为：
|
||
|
||
```python
|
||
def 尝试读取文本文件(文件路径: str, 默认值: str = "") -> str:
|
||
"""读取文本文件，失败时返回默认值。"""
|
||
try:
|
||
with open(文件路径, "r", encoding="utf-8") as 文件对象:
|
||
return 文件对象.read()
|
||
except OSError:
|
||
return 默认值
|
||
```
|
||
|
||
异常中文化函数应单独封装：
|
||
|
||
```python
|
||
def 异常_转中文提示(异常对象: Exception) -> str:
|
||
"""把常见 Python 异常转换为中文提示。"""
|
||
异常类型 = type(异常对象).__name__
|
||
原始信息 = str(异常对象)
|
||
return f"{异常类型}：{原始信息}"
|
||
```
|
||
|
||
## PEP8 格式规范
|
||
|
||
易语言风格只改变命名表达，不改变 Python 的格式底线。代码必须遵守 PEP8。
|
||
|
||
要求：
|
||
|
||
- 使用 4 个空格缩进
|
||
- 顶层函数、类之间空 2 行
|
||
- 类方法之间空 1 行
|
||
- import 放在文件顶部
|
||
- 标准库、第三方库、本地库分组导入
|
||
- 行宽尽量控制在 88 到 100 个字符
|
||
- 运算符两侧保留空格
|
||
- 逗号后保留一个空格
|
||
- 函数默认参数写作 `参数: 类型 = 默认值`
|
||
- 文件末尾保留一个换行
|
||
- 优先使用 `ruff format` 或 `black` 格式化
|
||
|
||
推荐：
|
||
|
||
```python
|
||
import hashlib
|
||
|
||
|
||
def 计算SHA256(文本内容: str) -> str:
|
||
"""计算文本内容的 SHA256 摘要。"""
|
||
哈希对象 = hashlib.sha256()
|
||
哈希对象.update(文本内容.encode("utf-8"))
|
||
return 哈希对象.hexdigest()
|
||
```
|
||
|
||
不推荐：
|
||
|
||
```python
|
||
import hashlib
|
||
|
||
def 计算SHA256(文本内容):
|
||
哈希对象=hashlib.sha256();哈希对象.update(文本内容.encode('utf-8'));return 哈希对象.hexdigest()
|
||
```
|
||
|
||
## 常用代码模板
|
||
|
||
### UUID
|
||
|
||
```python
|
||
import uuid
|
||
|
||
|
||
def 取UUID() -> str:
|
||
"""生成随机 UUID 字符串。"""
|
||
return str(uuid.uuid4())
|
||
```
|
||
|
||
### 时间戳
|
||
|
||
```python
|
||
import time
|
||
|
||
|
||
def 取时间戳(毫秒: bool = False) -> int:
|
||
"""获取当前时间戳。"""
|
||
当前时间 = time.time()
|
||
if 毫秒:
|
||
return int(当前时间 * 1000)
|
||
return int(当前时间)
|
||
```
|
||
|
||
### 文本截取
|
||
|
||
```python
|
||
def 文本_取中间(文本: str, 左标记: str, 右标记: str) -> str:
|
||
"""提取两个标记之间的文本。"""
|
||
左位置 = 文本.find(左标记)
|
||
if 左位置 == -1:
|
||
return ""
|
||
|
||
开始位置 = 左位置 + len(左标记)
|
||
右位置 = 文本.find(右标记, 开始位置)
|
||
if 右位置 == -1:
|
||
return ""
|
||
|
||
return 文本[开始位置:右位置]
|
||
```
|
||
|
||
### JSON 文件
|
||
|
||
```python
|
||
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 格式保证可维护。
|