接手祖传代码想骂人？我用AI把注释补全了
上个月接手了一个老项目，打开代码仓库的那一刻，人差点没了。
三百多个文件，没有一行注释。变量名全是a、b、c、tmp、data、res，函数名清一色的handleClick、getData、setInfo。看到一个叫getData的函数，里面有二十多行，调了三个外部接口、做了一堆数据转换、最后还更新了全局状态，但我完全不知道它到底在干什么。
这事其实挺常见的。项目赶工期的时候，谁有空写注释？先上线再说，以后有空补——然后就再也没有以后了。
接手这种代码，大概要花一到两周才能看懂整个业务逻辑，中间还要不断问之前的同事，特别浪费时间。后来我试着让AI帮忙反向生成注释和文档，发现效果还不错。分享几个实测好用的方法。
平时做代码整理和重构的时候习惯用AI辅助，一个入口同时对比几个模型对同一段代码的理解，不用来回切（gemini-zh.xyz），实测下来Claude和DeepSeek在代码理解上都挺到位。下面直接说实操。
方法一：函数级别逐行上注释
最基础的操作——把一段没有注释的函数扔给AI，让它逐行加上中文注释。
上周处理了一个订单状态流转的函数，四十多行，各种if判断和状态码，完全看不懂。复制出来之后给AI的指令很简单：
“以下是一段Python代码，没有任何注释。请帮我逐行或逐段加上中文注释，说明每一部分在做什么，不要修改代码本身。”
大概十几秒之后，AI返回了带注释的版本。原来的几个状态码全是数字（1、2、3、4、5），加上注释之后我才知道1是待支付、2是已支付待发货、3是已发货、4是已完成、5是已取消。状态流转的逻辑一下子就清晰了。
不用自己猜，也不用翻文档，省了很多时间。
方法二：从代码反向生成流程图
有时候光看注释还不够——状态流转和分支逻辑太多的时候，视觉化的流程图更能帮助理解。
选了一个特别复杂的函数，里面嵌套了五六层if-else，还有两个switch。同样把代码贴给AI，指令换成：
“帮我梳理这个函数的执行流程，用文字描述的形式输出一个流程图。按步骤标注每一步在什么条件下走哪条分支，以及每步调用了什么外部方法。”
AI返回了一份清晰的步骤列表，把每个分支条件都标注出来了。对照着这份列表，我花半小时在draw.io上画了张图，后面团队新同事看代码的时候，直接看这张图就能理解整个流程，不用再从头啃一遍。
方法三：整理接口文档
老项目的另一个问题——没有接口文档。
前端调后端接口，全靠看代码猜参数格式。猜错了调不通，调通了也不知道是不是标准用法。有个接口有七八个参数，其中三个是必填的，没有任何文档说明。
把接口相关的代码片段整理出来（Controller层和Service层），交给AI：
“以下是一个接口的Controller和Service层代码，请帮我生成一份接口文档，包含接口路径、请求方法、请求参数（含是否必填和类型）、响应格式。输出Markdown表格格式。”
AI把参数列表整理成了表格，还在必填参数后面标注了说明。虽然一些业务含义需要额外确认，但最耗时的信息整理工作直接省掉了。
方法四：解释复杂的代码块
有些代码块特别长，一眼看过去头大。这时不用把整段代码都扔进去，只需要选中读不懂的部分，单独给AI看，问它“这段代码在做什么”就好。
昨天看到一个二十多行的数据聚合逻辑，用了三个循环嵌套加一个reduce，完全看不出最终要输出什么结构。单拎出来给AI解释，它告诉我是“把订单列表按用户ID分组，统计每个用户的订单总额和平均金额，然后按总额降序排序”。一句话说清楚之后，再看代码就没那么难了。
几个用得最多的指令模板
模板一：补注释
以下是一段【语言】代码，没有任何注释。请帮我逐行或逐段加上中文注释，说明每一部分在做什么。不要修改代码本身，只添加注释。
【粘贴代码】
模板二：梳理流程
帮我梳理这个函数的执行流程，用步骤列表的形式输出。标注每一步在什么条件下走哪条分支，以及调用了什么关键方法。
【粘贴函数代码】
模板三：生成接口文档
以下是一个接口的相关代码，请帮我生成接口文档，包含：路径、方法、请求参数（含是否必填和类型）、响应格式。用Markdown表格输出。
【粘贴Controller和Service代码】
模板四：理解复杂逻辑
下面这段代码我看不太懂，请用大白话解释一下它在做什么。不需要分析每行代码，只需要告诉我整体逻辑和最终输出是什么。
【粘贴代码块】
一些小提醒
AI生成的注释偶尔会有偏差。特别是涉及特殊业务逻辑的地方，比如状态码的枚举值、优惠计算的具体规则等。这类内容建议人工复核一遍，确保注释和实际代码行为一致。
生成的注释风格也可能不统一。如果团队有注释规范，最好在指令里明确说明（比如“使用中文、每行代码前用#号”），这样输出结果更容易直接用。
另外，涉及敏感业务逻辑的代码不建议给外部AI工具。可以脱敏之后再处理——比如把变量名改成通用名称，或者只提取不涉密的部分。如果公司有内部部署的AI，优先用内部的。
总结
给老代码补注释这件事，之前完全靠手工。看一行、理解一行、写一行注释，效率很低，还容易看走眼。
用AI做这个事，思路其实很简单——让AI先把代码“翻译”成人类能理解的语言，再由人工确认和修正。这个过程能省掉大部分“读代码”的时间，把精力集中在“验证和理解业务逻辑”上。
如果你手头也有那种“前人写得很爽、后人读得很累”的代码，可以试试上面这几个方法。
