命名与代码风格

命名约定、格式化、注释与可读性

命名约定

通用规则

[Requirement] 命名必须使用英文，禁止使用拼音或拼音缩写。

[Standard] 标识符应见名知意，不使用无意义的单字母（循环变量 i/j/k 除外）。

元素	风格	示例
类名	PascalCase	`UserService`、`HttpRequest`
函数/方法	snake_case	`get_user_by_id()`
变量	snake_case	`user_name`、`order_count`
常量	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`
模块/包	snake_case	`user_service.py`
布尔变量	is/has/can 前缀	`is_valid`、`has_permission`
异常类	`Error`/`Exception` 后缀	`ConfigNotFoundError`

具体规则

[Requirement] 布尔变量必须以 is/has/can/should 开头，避免歧义。

[Standard] 集合类型变量使用复数或带集合后缀：users、user_list、order_map。

[Caution] 避免在命名中包含类型信息（如 user_str、name_list），除非类型本身就是业务语义的一部分。

示例：

# 正确
is_active = True
user_list = get_users()
order_count = len(orders)
 
# 错误
active = True
lst = get_users()
cnt = len(orders)

格式化工具

[Requirement] 项目必须配置格式化工具，且 CI 中强制校验，未通过格式化的代码不得合并。

语言	格式化工具	Lint 工具
Python	`black` + `isort`	`ruff` 或 `flake8`
JavaScript/TypeScript	`prettier`	`eslint`
Go	`gofmt` / `goimports`	`golangci-lint`
Java	`google-java-format`	`checkstyle`

[Standard] 缩进统一使用 4 个空格（Python）或 2 个空格（JS/TS），禁止 Tab 与空格混用。

[Default] 每行最大长度：Python 100 字符，JS/TS 120 字符。

[Suggestion] 在 pre-commit hook 中运行格式化与 lint，本地提交前自动检查。

注释规范

写什么注释

[Standard] 注释”为什么”，而不是”做什么”。代码本身应能说明”做什么”。

[Requirement] 公共 API、公开函数/类必须有文档字符串（docstring），说明参数、返回值、异常。

[Caution] 代码与注释必须保持一致；修改代码时同步更新注释，过期的注释比没注释更糟。

示例：

def calculate_discount(price: float, user_level: int) -> float:
    """根据用户等级计算折扣价。
 
    等级 1-3 无折扣，4-6 九折，7 级以上八折。
    该映射与运营配置保持一致，修改前需确认。
 
    Args:
        price: 原始价格，必须 >= 0。
        user_level: 用户等级，1-10。
 
    Returns:
        折扣后价格。
 
    Raises:
        ValueError: price < 0 或 user_level 超出范围。
    """
    if price < 0:
        raise ValueError("price must be non-negative")
    ...

反模式

# 错误：注释在重复代码的字面意思
count += 1   # count 加 1
 
# 错误：被注释掉的代码
# def old_logic():
#     ...

可读性准则

[Standard] 单个函数不超过 50 行；超过时按职责拆分。

[Standard] 函数参数不超过 5 个；超过时使用数据类（dataclass）或配置对象封装。

[Default] 嵌套层级不超过 3 层；超过时提取子函数或使用提前返回（guard clause）。

[Suggestion] 优先使用提前返回减少嵌套：

# 正确：提前返回
def get_user(user_id: int):
    if user_id <= 0:
        return None
    user = db.query(user_id)
    if user is None:
        return None
    if not user.is_active:
        return None
    return user

反模式：

# 错误：深层嵌套
def get_user(user_id):
    if user_id > 0:
        user = db.query(user_id)
        if user is not None:
            if user.is_active:
                return user
            else:
                return None
        else:
            return None
    else:
        return None

反模式

反模式	说明	改进方向
魔法数字	代码中出现未命名的数字常量	提取为命名常量或枚举
超长函数	单函数超过 100 行	按职责拆分
深层嵌套	`if/for` 嵌套超过 4 层	提前返回、提取子函数
无意义命名	`data`、`info`、`tmp`、`obj`	使用能表达语义的名字
注释掉的代码	保留大量被注释的旧代码	直接删除，版本控制可追溯
缩写泛滥	`usr`、`ord`、`amt`	使用完整单词 `user`、`order`、`amount`