AI 提示词助力代码重构：提升可读性的实践指南

# 反例：变量名无意义，函数名未体现功能
def func(a, b):
    x = a + b
    y = x * 2
    return y

vs

# 正例：变量名说明数据含义，函数名体现计算逻辑
def calculate_double_sum(first_num: int, second_num: int) -> int:
    sum_result = first_num + second_num
    double_sum = sum_result * 2
    return double_sum

函数设计

1. 单一职责（仅完成 1 个核心功能）
2. 函数长度≤80 行（非绝对，需结合场景）
3. 参数数量≤5 个（避免'参数爆炸'）

// 反例：1 个函数同时处理数据读取、计算、输出
public void processData(String filePath) {
    // 1. 读取文件
    List<String> data = new ArrayList<>();
    try (BufferedReader br = new BufferedReader(new FileReader(filePath))) {
        String line;
        while ((line = br.readLine()) != null) {
            data.add(line);
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
    // 2. 计算平均值
    double sum = 0;
    for (String s : data) {
        sum += Double.parseDouble(s);
    }
    double avg = sum / data.size();
    // 3. 输出结果
    System.out.println("平均值：" + avg);
}

vs

// 正例：拆分 3 个单一职责函数，逻辑分层清晰
public class DataProcessor {
    // 仅负责读取文件
    public List<Double> readDataFromFile(String filePath) throws IOException {
        List<Double> data = new ArrayList<>();
        try (BufferedReader br = new BufferedReader(new FileReader(filePath))) {
            String line;
            while ((line = br.readLine()) != null) {
                data.add(Double.parseDouble(line));
            }
        }
        return data;
    }
    // 仅负责计算平均值
    public double calculateAverage(List<Double> data) {
        double sum = 0;
        for (double num : data) {
            sum += num;
        }
        return sum / data.size();
    }
    // 仅负责输出结果
    public void printResult(double average) {
        System.out.println("数据平均值：" + average);
    }
}

逻辑简化

1. 避免多层嵌套（≤3 层）
2. 减少冗余判断（如用三元运算符/枚举替代复杂 if-else）
3. 消除死代码/未使用变量

// 反例：4 层嵌套 + 冗余判断
function getDiscount(price, userType, isNewUser, hasCoupon) {
    let discount = 0;
    if (userType === "VIP") {
        if (isNewUser) {
            discount = 0.8;
            if (hasCoupon) {
                discount = 0.7;
            }
        } else {
            if (hasCoupon) {
                discount = 0.85;
            } else {
                discount = 0.9;
            }
        }
    }
    return price * discount;
}

vs

// 正例：用对象映射替代嵌套，逻辑扁平化
function getDiscount(price, userType, isNewUser, hasCoupon) {
    // 定义折扣规则映射表，清晰可见
    const discountRules = {
        VIP: { new: { coupon: 0.7, noCoupon: 0.8 }, old: { coupon: 0.85, noCoupon: 0.9 } },
        normal: { new: { coupon: 0.95, noCoupon: 1.0 }, old: { coupon: 0.98, noCoupon: 1.0 } }
    };
    // 简化判断逻辑
    const userTier = isNewUser ? "new" : "old";
    const couponStatus = hasCoupon ? "coupon" : "noCoupon";
    const discount = discountRules[userType]?.[userTier]?.[couponStatus] || 1.0;
    return price * discount;
}

注释完整性

1. 类/函数需有文档注释（说明功能、参数、返回值）
2. 复杂逻辑处需有单行注释（解释'为什么'而非'是什么'）
3. 避免过时注释（注释与代码逻辑一致）

# 反例：无文档注释，复杂逻辑无说明
def format_date(date_str):
    parts = date_str.split("-")
    if len(parts) == 3:
        return f"{parts[2]}/{parts[1]}/{parts[0]}"
    else:
        return "Invalid"

vs

# 正例：完整文档注释 + 逻辑说明
def format_date(date_str: str) -> str:
    """将 ISO 日期格式（YYYY-MM-DD）转换为日/月/年格式（DD/MM/YYYY）
    参数：
        date_str: str - 输入的日期字符串，需符合 ISO 格式（如"2024-05-20"）
    返回：
        str - 转换后的日期字符串，若格式无效则返回"Invalid Date"
    说明：
        1. 先按"-"分割字符串，判断是否为 3 个部分（年/月/日）
        2. 若格式正确，重组为 DD/MM/YYYY；否则返回无效提示
    """
    parts = date_str.split("-")
    # 验证 ISO 格式有效性（长度为 3 且各部分为数字）
    if len(parts) == 3 and all(part.isdigit() for part in parts):
        return f"{parts[2]}/{parts[1]}/{parts[0]}"
    else:
        return "Invalid Date"

代码复用

1. 提取重复逻辑为公共函数/工具类
2. 避免硬编码（用常量/配置替代魔法值）
3. 遵循 DRY 原则（Don't Repeat Yourself）

// 反例：重复计算逻辑 + 硬编码魔法值
public class OrderCalculator {
    // 计算 A 商品总价：重复逻辑
    public double calculateProductA(double quantity) {
        return quantity * 99.9; // 硬编码单价
    }
    // 计算 B 商品总价：重复逻辑
    public double calculateProductB(double quantity) {
        return quantity * 199.9; // 硬编码单价
    }
}

vs

// 正例：提取公共方法 + 定义常量
public class OrderCalculator {
    // 定义商品单价常量，集中管理
    private static final double PRODUCT_A_PRICE = 99.9;
    private static final double PRODUCT_B_PRICE = 199.9;
    
    // 公共计算方法，复用逻辑
    private double calculateProductTotal(double quantity, double price) {
        return quantity * price;
    }
    
    // 调用公共方法，避免重复
    public double calculateProductA(double quantity) {
        return calculateProductTotal(quantity, PRODUCT_A_PRICE);
    }
    
    public double calculateProductB(double quantity) {
        return calculateProductTotal(quantity, PRODUCT_B_PRICE);
    }
}

三、重构建议 Prompt 的设计框架：从基础到进阶

重构建议 Prompt 的核心目标是'让 LLM 精准理解代码问题，并生成可执行的重构方案'。其设计需遵循'明确指令 + 上下文信息 + 约束条件'的结构，不同复杂度的场景对应不同的 Prompt 模板。以下分基础版、进阶版、专家版三个层级，拆解 Prompt 的设计逻辑，并结合案例说明适用场景。

（一）基础版 Prompt：适用于简单代码片段重构

核心场景：新手开发人员处理独立函数/代码块（如单个 Python 函数、Java 方法），需解决基础可读性问题（命名、简单嵌套、注释缺失）。 设计逻辑：以'原始代码 + 核心需求'为核心，减少额外约束，让模型聚焦基础优化。 模板结构：

指令：作为一名资深软件开发工程师，请帮我重构以下代码，提升其可读性。
原始代码：[粘贴待重构的代码片段]
重构要求：
1. 优化命名（变量名、函数名需体现功能，避免歧义）；
2. 简化逻辑（消除冗余判断、减少嵌套）；
3. 补充必要注释（函数文档注释 + 复杂逻辑单行注释）；
4. 输出格式：先提供重构后的完整代码，再分点说明重构点及原因。

实战案例：重构 Python 数据处理函数

1. 待重构代码（新手编写，存在命名模糊、无注释、冗余逻辑问题）：

def f1(d, k):
    res = []
    for i in d:
        if i == k:
            v = d[i]
            if v > 10:
                res.append(v)
    return res

2. 基础版 Prompt 完整输入：

指令：作为一名资深 Python 开发工程师，请帮我重构以下代码，提升其可读性。
原始代码：
def f1(d, k):
    res = []
    for i in d:
        if i == k:
            v = d[i]
            if v > 10:
                res.append(v)
    return res
重构要求：
1. 优化命名（变量名、函数名需体现功能，避免歧义，遵循 Python 蛇形命名法）；
2. 简化逻辑（消除冗余判断、减少嵌套，可使用列表推导式）；
3. 补充必要注释（函数需有文档注释，说明参数、返回值、功能；复杂逻辑处需单行注释）；
4. 输出格式：先提供重构后的完整代码，再分点说明重构点及原因。

3. 模型输出结果：

# 重构后的代码
def filter_dict_values_by_key(dict_data: dict, target_key: str) -> list:
    """根据指定键筛选字典中大于 10 的值，并返回结果列表
    参数：
        dict_data: dict - 输入的字典，键为字符串类型，值为数字类型
        target_key: str - 需要筛选的目标键
    返回：
        list - 符合条件的值组成的列表（仅包含 target_key 对应的值且该值>10）
    """
    # 使用列表推导式简化循环 + 判断逻辑，减少嵌套层级
    return [value for key, value in dict_data.items() if key == target_key and value > 10]

# 重构点及原因说明：
# 1. 函数名优化：将"f1"改为"filter_dict_values_by_key"，直接体现'按键筛选字典值'的核心功能，符合 Python 命名规范；
# 2. 参数名优化：将"d"改为"dict_data"（明确为字典数据），"k"改为"target_key"（明确为目标键），避免歧义；
# 3. 变量名优化：删除冗余变量"v"（直接用"value"替代），删除临时变量"res"（用列表推导式直接返回结果）；
# 4. 逻辑简化：将 2 层 for-if 嵌套改为 1 层列表推导式，代码行数从 8 行减少到 1 行，且逻辑更直观；
# 5. 注释补充：添加完整文档注释（说明功能、参数、返回值），为列表推导式添加单行注释，解释逻辑目的。

4. 效果验证：重构后的代码满足所有可读性维度——命名清晰、逻辑扁平化、注释完整，新手可直接理解功能，且可复用性提升（函数名明确，无需猜测用途）。

（二）进阶版 Prompt：适用于模块级重构与行业规范

核心场景：中高级开发人员处理多函数/类的模块重构（如一个 Python 工具类、Java 服务层模块），需符合行业特定规范（如 Google 代码规范、RESTful API 开发规范）或框架约束（如 Spring Boot、Django）。 设计逻辑：在基础版上增加'上下文信息'（如模块功能、使用框架、行业规范）和'进阶需求'（如依赖管理、性能优化、兼容性保障），让模型生成符合实际项目场景的方案。 模板结构：

指令：作为一名熟悉 [框架/行业] 的资深开发工程师，请帮我重构以下模块代码，需符合 [行业规范]，同时保障重构后功能一致性。
模块上下文：
1. 模块功能：[说明该模块的核心作用，如'用户订单数据处理模块，负责订单创建、价格计算、状态更新']；
2. 技术栈：[说明使用的框架/语言版本，如'Java 17 + Spring Boot 3.0，数据库为 MySQL 8.0']；
3. 依赖关系：[说明该模块与其他模块的关联，如'依赖用户模块（获取用户等级）、商品模块（获取商品单价）']；
重构要求：
1. 结构优化：按 [设计原则，如'单一职责原则'] 拆分类/函数，避免一个类承担过多功能；
2. 规范适配：符合 [具体规范，如'Google Java 代码规范'