1. 为什么你需要一条“代码卫生”流水线先说个真实场景。上个月我接手了一个维护了三年的老项目第一个需求改起来差点把我劝退一个UserController类3000多行里面有一堆getUserInfo、getUserInfo2、getUserInfoNew还有注释掉的旧逻辑、复制粘贴过来又改了半天的工具方法、一个看起来没用但谁也不敢删的StringUtil……改一个字段全局搜索能找到十几个相关点每个都得点开看一遍才能确定改哪个。这种项目没人敢动手不是因为需求难而是“代码卫生”太差——你永远不知道面前这堆代码哪些是活资产哪些是历史遗留的定时炸弹。后来我给自己定了一条规矩每次动代码之前先做一轮“清扫”。这个习惯慢慢固化成了六步也就是今天想分享的Hygiene-sweep——一条代码卫生六步清扫skill。它不是什么高深的理论更像是一份“进场前先戴手套、动手前先盘点现场”的作业流程把散乱的代码清理思维整理成了一套可以照着执行的操作清单。这条skill解决的是三个问题一是帮你快速摸清项目底细别一上来就埋头改代码二是用低成本的手段把“坏味道”集中清掉避免小问题滚成大坑三是把清理动作和日常开发节奏结合让卫生检查不再是“大扫除日”才做的特殊活动。适合的人群很宽——不管是刚接手新项目的人、带团队做代码评审的TL还是整天和遗留系统打交道的维护者这套流程都能直接拿过去用。我把它封装成skill本质上是把“怎么做代码卫生”这件事从隐性经验变成了显性流程——不靠个人感觉不靠某个前辈的灵光一现每一条都是可重复、可检查、可执行的动作。下面从头拆解这套六步清扫法的设计思路和实操细节。2. 六步清扫的完整拆解从“看到什么”到“怎么处理”2.1 第一步盘点现状先把项目的“器官”摸清楚清扫的第一步不是动手删代码而是做一次现状盘点。就像家政打扫之前先要在房子里转一圈看看哪些地方积灰、哪些地方堆了杂物、有没有漏水隐患一样代码卫生的第一步是搞清楚这个项目的核心模块有哪些每个模块的代码量多少改动频繁的是哪几块哪些文件是“陈年古迹”哪些是最近还在活跃迭代的我在实际操作中习惯用一个三维度盘点法。第一维度是“活跃度”看代码文件的最近修改时间结合Git log统计最近三个月内被改动过的文件列表那些长期没动过的文件大概率是稳定逻辑优先级偏低第二维度是“复杂度”用代码分析工具跑一遍圈复杂度Cyclomatic Complexity高于10的函数一眼就能圈出来这些是后续重读和修改的重点风险区第三维度是“耦合度”看看哪些类被大量其他模块引用——Util、Common、Helper这类“公共类”如果被几十个地方引用动它的成本极高必须放在清单里重点标注。这个步骤的目标产出物是一份“清扫清单”。不一定非要写成正式文档我在个人项目里通常只是维护一个TODO-CLEAN.md文件随手记录三件事文件路径、发现的问题类型命名混乱/重复代码/死代码/结构不合理、预估风险等级。别小看这一份清单它让你从“感觉代码很乱”变成了“我知道乱在哪、为什么乱、优先级是什么”这就是可执行清扫的第一步。值得强调的是这个盘点阶段的工具并不求全能用grep、find加Git命令解决的事不需要上重型平台。我的习惯是先用git log --name-only拿到文件活跃度再用一个简单的圈复杂度计算脚本很多IDE自带或者可以装插件快速标记高风险区半个小时就能完成一个小型项目的初步体检。2.2 第二步消灭“命名坏味道”让代码会说话清扫的第二件事是收拾命名。代码里的命名就像是房间里的标签——一个叫“数据1”的文件夹和一个叫“2024年Q3财务对账单”的文件夹找东西的体验天差地别。代码卫生最直接的“脏乱差”就是命名问题而这个问题恰恰是新手最常忽视的。我在清理时会把命名问题分成几类每一类对应不同的处理方式。第一类是“语义模糊”data、info、temp、result这样的通用命名出现在哪里都行但放在哪里都说不清楚含义。处理方式是结合上下文重命名为具体语义的标识符比如data在用户登录场景下拆成loginRequest或authPayload。第二类是“信息冗余”getUserInfo和getUserInfo2的问题是后缀数字本身就在告诉别人“代码失控了”。重命名不只是简单改掉数字而是要区分两个方法各自的真实职责——getUserBasicInfo和getUserProfile之类让名字直接表达差异。第三类是“误导性命名”这类最危险比如一个方法叫isExpired却返回了“是否未过期”的逻辑。命名清理看起来是小动作实际上牵一发动全身——因为改一个公开方法名所有调用点都要跟着改。所以这里我给一个实用建议命名清理优先做“局部变量和私有方法”因为影响范围可控而对外公开的API、公共类的公有方法除非有配套的自动化测试兜底否则不建议在清扫阶段大动干戈。这属于“卫生”和“重构”的边界问题——清扫解决的是“脏”重构解决的是“乱”两者可以同时启动但节奏不能混。2.3 第三步做减法删掉“看起来没用但不敢删”的死代码代码卫生和居家大扫除最像的一点就是断舍离。项目里躺着大量“看起来没用但不敢删”的代码——注释掉的逻辑、从未被调用的工具方法、遗留的兼容分支、死掉的功能开关。留着它们的心理逻辑通常是“说不定以后用得上”但这个“以后”往往永远不会来反而让后来人每次读到那里都要停下来思考“这段代码还有用吗”我的删除策略分三个层级。第一层是“可以安全删”被注释掉的整段代码Git历史里有完整记录真想找回完全可以从版本库恢复留在现场反而是噪音没有被任何地方引用的私有方法静态分析工具能直接查出来。第二层是“确认后删”有些代码看起来没人调用但可能是通过反射、Spring注入这类动态机制使用的删之前要全局搜索一下字符串引用确认是动态调用就先标注别急着动手。第三层是“标注不动”明确知道是历史包袱但暂时没有精力收尾的代码用DeprecatedJava或者deprecated标签标注让IDE和静态分析工具自动高亮提醒所有后续维护者绕道走。删代码有个经典的心智负担觉得删掉就等于“损失”。我自己走过这个阶段后想明白一件事——代码库里只有两种代码一种是被执行的负责产生价值另一种是不被执行的负责制造困惑。你删掉的不被执行的代码没有损失任何可运行的价值反而消除了大量的理解成本。只要确信这些逻辑都被版本控制保底删除就是最安全的改动。这一步操作上强烈建议配合IDE的“Find Usages”功能逐个确认而不是凭感觉笃定“这个肯定没用了”。我开始也吃过亏凭直觉删了一个“没人调用”的工具方法结果在另一个模块里通过反射动态加载了它上线直接炸了。从那以后凡是被删除的目标哪怕确认了99%我都会全局搜一遍完整字符串这多花一分钟能省掉通宵排查的十个小时。2.4 第四步理结构把“堆满杂物的房间”重新分区处理好表面灰尘之后要处理的是更深层的结构问题。我把这步称作“重新分区”——项目文件就像房间的收纳体系刚住进去的时候也许还算整齐但三年下来什么东西随手放在哪就变成什么样了工具方法堆在一个巨型类里、业务逻辑和底层数据访问混在一起、一个函数承担了“校验参数查询数据组装返回记录日志”四重工作。分区清理的第一优先级是“处理巨型函数”。一个超过50行、条件分支超过5个的函数阅读成本呈指数级上升。处理方式是按职责拆成两个或更多小函数拆分的核心是找到“可以独立命名”的代码块——凡是能用一个动词短语概括的连续代码段就有资格拆出来。比如“校验用户输入”是一个职责“组装查询条件”是一个职责“格式化返回结果”是一个职责混在一起就是灾难。第二优先级是“处理明显的‘卧底’依赖”。什么叫卧底就是一个本该只管展示的页面层里面直接new了数据库查询对象一个本该处理计算逻辑的工具类里面混进了文件IO操作。这类问题的本质是分层不清晰修起来往往需要牵动很多依赖方所以清扫阶段我的建议不是全面推翻重建而是“止血”先把错位的调用标记出来在注释里说明“此处绕过Service层直接访问DAO待重构”至少让后来人知道这是已知问题而不是无意写出的坏代码。第三优先级是“重复代码的合并”。两段逻辑一样的代码复制在项目里两个地方是最让人头疼的维护陷阱——你改了一处另一处没改行为就开始分叉。清扫时如果发现纯复制粘贴的重复代码抽取为公共方法如果发现的是“改了几个变量还是同一个骨架”的相似代码考虑用参数化或模板方法统一。2.5 第五步建护栏让卫生问题不再“回潮”清扫不能只靠一次性的大扫除还得建立日常“防尘机制”。第五步的核心是引入自动化检查工具把能交给机器判断的卫生规则全部交给机器。我的脚手架配置一般包括这么几层。第一层是lint工具Python系用flake8或ruffJavaScript系用ESLintJava系用checkstyle——它们负责在提交代码时就拦住明显的命名不规范、未使用变量、导入顺序混乱等基础问题。第二层是格式化工具prettier、black、gofmt这些工具的意义不在于某个人审美多强而在于统一——统一的格式让团队代码看起来像一个人写的大大降低阅读摩擦。第三层是静态复杂度检查比如eslint的complexity规则或者Python的mccabe插件把圈复杂度阈值设为10超过就报错逼迫大家在函数变大之前就拆。这层机制最容易被误解成“限制开发自由”。实际上把卫生规则交给机器之后人的精力反而被解放了——你不需要在Code Review时浪费时间争论“这里是不是该换个名字”“这里空行是不是多了”这些琐碎争议全部自动化解决评审时间就剩下来专注讨论逻辑正确性和设计合理性。我在项目里还有一个习惯把lint和格式化挂到Git的pre-commit钩子上利用husky前端、pre-commitPython这类工具在代码提交前自动执行检查和修格式。一开始队友可能会抱怨“怎么提交这么慢”但跑一个lint加格式化通常只需几秒换来的是代码库永远保持一个统一的起点。2.6 第六步固化成惯例让卫生融入开发节奏最后一步不是技术操作而是流程习惯。代码卫生六步清扫最大的陷阱是“清扫一次半年后再想起来”。所以第六步是把清扫动作固化到日常开发的节奏里让卫生成为惯性而不是例外。我的做法是设置“三个触发点”。第一个触发点新任务开始前花30分钟浏览相关代码区域把顺手能清理的命名、死代码、小结构问题在开发过程中随手处理掉而不是等要改的代码堆成山再一起扛。第二个触发点功能合入主干前快速过一遍自己本次改动的Diff检查是否带入了不规范的命名、未经使用的变量、复制粘贴遗留的代码——这是在提交前最后一道自我检视的关卡。第三个触发点每个迭代结束后安排一次专门的“卫生日”或“卫生时间盒”按照六步流程系统性地清扫一次并结合团队成员在开发中积累的“小问题清单”。这个习惯真正起效的关键是“降低单次清扫规模”。很多人洗完一次代码库因为动作太大、时间太长产生了强烈的疲惫感从此再也不愿意做这件事。但如果你把清扫拆成每周一次的小动作每次只处理清单里的几项效果累加起来远比那一次性大扫除要好。我自己深有体会每次改动代码时顺手清理20分钟比集中花一天做“清理大会”的效率高得多而且不会因为打断正常开发节奏而招来抵触。3. 用一个真实案例把六步走一遍理论说多了容易空拿一个我最近实际清扫过的模块来演示一遍完整的流程。接手的是一个订单导出功能模块文件不大但脏乱特性齐全。核心的OrderExporter类有400多行一个exportOrders方法就占了两百多行里面有文件输出逻辑、Excel模板填充逻辑、数据查询逻辑、字段映射逻辑全串在一个函数里。方法命名也是老味道getList、getOrderData、processData、processData2不点进去看实现根本不知道它们各自到底处理什么。代码中间还夹着一大段被注释掉的旧版逻辑——就是那种“现在不用了但又舍不得删”的典型遗留。第一步盘点花的时间不多因为模块边界还算清楚。我用Git log确认了这个模块最近三个月只有两个提交属于改动频率较低但一旦改就牵动下游导出的核心模块复杂度上也确认了exportOrders是头号风险目标于是把整个文件的清扫优先级定成最高。第二步入手清理命名。getList更名为queryPendingOrdersprocessData2拆成了formatCellValue和convertFieldToColumn两个职责明确的小函数。这一步我严格控制了范围——只改了私有方法对外公开的exportOrders签名保持不变避免影响到已知的两个调用方。第三步做删除。那一大段注释掉的旧逻辑直接删除从Git历史里能找回原样。同时发现一个只被exportOrders使用过一次的generateTempFile方法确认完没有其他调用点后也一并移除。第四步处理结构。这是这次清扫里工作量最大的一步。我把两百多行的exportOrders按职责拆成了四个函数validateExportParams负责入口校验、fetchOrderData负责数据查询、buildExcelBuffer负责用模板构建输出文件、writeToTargetPath负责落盘。拆完之后整个方法的阅读体验完全变了——从“一个两百行的大杂烩”到“一屏就能扫完的控制流程”。第五步配置护栏。因为这是一个Java项目我在相关目录的构建配置里加上了checkstyle的检查规则集阈值设为圈复杂度不超过10以后再有新代码试图往一个函数里堆逻辑提交阶段就会被警告。同时把这个模块的命名规范和格式规范纳入CI检查范围。第六步固化习惯。我在团队的知识库里更新了这个模块的“清扫记录”说明哪些类被拆过、哪些方法被重命名过、后续新需求优先加在哪个函数上。这份记录只有两百来字但极大降低了后来者重新摸索成本。整个过程断断续续做了大概四个小时其中纯编码时间两小时左右剩下的时间是确认行为边界和执行测试回归。清理完跑了一遍原有测试用例再加了一个抽查手动执行一次订单导出比对生成的文件和改动前的样板文件内容一致。确认没有问题之后整个改动合入主干。这个例子想说明的是六步清扫不需要你专门请假一天来做大工程把它当作嵌入式的小任务跟着需求改动一起推进才是可持续的节奏。4. 把六步流程封装成skill的实操思路标题里的“skill”不是随便加的我确实把六步清扫流程按照skill的模式固化了。现在不少AI辅助编程工具和agent框架都支持自定义skill核心逻辑就是把一段经验流程写成一个结构化的描述文件让AI在接手具体任务时能按这个流程走而不是每次都即兴发挥。把Hygiene-sweep封装成skill等于把上面这套六步方法变成了一个可以反复调用的“能力包”。一个skill文件通常包含三部分name和description用于让AI识别什么时候该调用这个能力instructions是整个skill的核心描述具体执行步骤和规则可选的examples则用来给出参考场景。我这里给一个精简但可用的skill描述示例。名字起作Hygiene-sweep说明写清楚“当需要审查或清理一个代码库、模块、文件时触发用于识别命名问题、死代码、重复逻辑和结构混乱并按六步流程输出清理建议”。instructions部分我会把六步写成明确的指令序列并对每一步补充操作细节比如“第1步盘点使用代码搜索和仓库历史检查列出文件的活跃度、复杂度与依赖范围”“第2步命名优先处理私有成员公共API需有测试覆盖方可改名”等等。为了让AI输出可落地我还会要求它以表格或多级列表的形式给出“清理清单”每个条目包含“文件路径—发现的问题——建议动作—风险级别”上文提到的TODO-CLEAN.md结构。如果你也在用agent类的开发环境封装skill有一个容易被忽略的好处AI每次帮你处理代码时会按照你和它约定的流程走而不是凭模型内部的“平均经验”。这意味着你自己踩坑换来的教训——比如“删除前全局搜索动态引用”“公共方法重命名必须看测试覆盖”这类反直觉细节——可以沉淀下来变成AI协作时的硬约束。我自己就是一个很典型的例子第一次让AI辅助清理代码时它大刀阔斧地建议我删掉了一堆“从未引用”的方法结果好几个是Spring通过配置注入的。把这条教训写进skill的规则后这个坑再也没踩过。5. 实操中的常见问题与排查技巧代码卫生这个事听起来简单真正动手时会遇到各种实际情况。我把踩过的坑和排查思路整理成一个速查表按出现频率排序供大家参考。问题典型场景排查思路与处理删除“死代码”后运行异常删除的私有方法被反射/动态代理调用或代码生成器自动生成后不再使用但保留引用删除前全局搜索方法名字符串异常时直接用Git revert恢复再用“调用栈反向定位”确认引用来源重命名公共方法后编译失败其他模块、配置文件或文档中仍有旧引用先改定义再改引用用IDE的Refactor功能批量重命名Java系用IntelliJ、前端用TS的全局引用查找避免手改遗漏拆函数后人觉得逻辑没变但行为变了拆分时不小心把有副作用的语句移到了新的依赖顺序之后拆完后跑全量相关测试没有测试的模块用“黄金文件对比法”——改动前后各跑一次对比输出文件差异格式化工具和团队现有代码风格冲突项目里混杂了旧代码和部分新同学“顺手美化”的代码先引入格式配置文件只对新代码生效老代码保持原样用“增量格式化”代替全量清洗清理后测试全绿但线上统计数据对不上清理阶段顺手改了一些“看起来等价”的常量或日志逻辑大原则是清扫阶段不做任何行为等价之外的改动——常量数值、收敛阈值这类“微小调整”应该单独发起不要混入卫生批次还有一个非常实用的排查思路在无法确认一处代码是否还有用的情况下启用“观察法”。给它打上日志或者记一个临时计数观察一个真实业务周期内是否被访问。如果一整个迭代周期内完全无访问记录再回头删除说服力和安全性都高得多。这招在处理“旧系统里的遗留接口”时尤其管用比我之前“拍脑袋直接删”的方式稳妥太多。最后聊一聊工具选择。现在静态分析领域可选工具非常多但我不建议一上来就配一整排检查器。我个人的经验是先上一个格式化工具再上一个lint工具跑两周让团队适应、把误报规则调一调然后再考虑圈复杂度检查和依赖分析。工具链是辅助清扫的不是用来制造对抗情绪的。项目里如果因为规则过严导致大家都在想办法绕过规则或者屏蔽检查那说明配置策略出了问题要做的不是“坚持规则”而是回到“卫生的目的”去重新设计规则。我个人在实际操作中的体会是代码卫生不是一次性的审美洁癖而是每次动手开发前给自己铺路的习惯。花四十分钟做一次小额清扫也许不会立刻提升什么性能指标但它能让下一次在这个模块上开发的人——不管是别人还是三个月后的自己——开始工作的时候少一些困惑多一些掌控感。这种回报看不见摸不着但是实打实的。六步清扫里的每一条都算不上新知识命名、删死代码、拆函数、lint检查……任何一本编程书里都翻得到。真正的价值是把它们串成一个完整流程并且每次动手都老老实实地走完。如果你也有一块“谁都不想碰”的老模块不妨从这个周末开始找出一个下午按这六步扫一遍试试。等代码变得干净了你会发现原来不想碰的模块后来变成了你愿意经常修修补补的地方。
