AI 提示词助力代码重构：提升可读性与可维护性

引言：代码重构与 Prompt 的关联价值

在软件开发生命周期中，代码重构是保障项目长期可维护性的关键环节。它并非修改功能逻辑，而是通过优化代码结构、命名规范、逻辑分层等方式，解决'坏代码'的典型问题——如函数过长、嵌套过深、命名模糊、重复代码堆积等。据行业调研显示，开发人员约 30% 的工作时间消耗在理解和修改低可读性代码上，而高效的重构能将后续维护成本降低 40% 以上。

传统重构依赖开发人员的经验积累：需要先识别代码中的'坏味道'，再依据设计模式（如单一职责原则、迪米特法则）制定重构方案，最后手动调整代码。这一过程对新手门槛高，且容易因主观判断偏差导致重构不彻底或引入新问题。

而重构建议 Prompt的出现，为这一流程提供了高效解决方案。通过向大语言模型（LLM）输入'原始代码 + 重构需求'，模型可基于海量代码训练数据，快速识别问题、生成符合行业规范的重构方案，并解释重构逻辑。这种方式不仅降低了重构的技术门槛，还能确保重构方案的一致性和规范性，尤其适合新手开发、遗留系统改造、团队标准化重构等场景。

本章将从'问题识别 - Prompt 设计 - 方案落地 - 效果验证'全流程，拆解重构建议 Prompt 的设计技巧，结合多语言案例，帮助读者掌握用 Prompt 提升代码可读性的核心方法。

核心概念：代码可读性的关键评价维度

在设计重构建议 Prompt 前，需先明确'代码可读性'的量化标准——这既是 Prompt 的核心指令依据，也是评估重构效果的标尺。行业普遍认可的可读性维度可分为以下 5 类，每类包含具体的评价指标和正反例对比：

命名规范

1. 命名与功能强关联
2. 避免缩写/歧义词汇
3. 遵循语言约定（如 Python 的蛇形命名、Java 的驼峰命名）

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

# 正例：变量名说明数据含义，函数名体现计算逻辑
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);
}

// 正例：拆分 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;
}

// 正例：用对象映射替代嵌套，逻辑扁平化
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"

# 正例：完整文档注释 + 逻辑说明
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; // 硬编码单价
    }
}

// 正例：提取公共方法 + 定义常量
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：适用于简单代码片段重构

核心场景：新手开发人员处理独立函数/代码块（如单个 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. 注释补充：添加完整文档注释（说明功能、参数、返回值），为列表推导式添加单行注释，解释逻辑目的。

（二）进阶版 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 代码规范'