cleanse

范围

如果用户指定了文件或目录，请检查这些内容。如果没有指定，请先询问他们想检查什么，再继续。

目标

让人初次接触这段代码时也能轻松理解。六个月后打开此文件的人应该能在几秒钟内明白它的作用。 所有更改都应保留原有功能和行为。

检查内容

仔细阅读目标代码，然后按以下顺序进行检查和修改。直接修改，不要只列出建议。

1. 扁平化控制流

嵌套条件是可读性最大的杀手。扁平化处理。

• 将 if/else 链转换为提前返回和守卫子句。把退出条件放在前面，把正常路径放在后面。
• 如果函数唯一有意义的路径被条件包裹，就反转条件并提前返回。
• 如果 else 块只执行 return 或 continue，就移除 else——提前返回已经处理了这种情况。

2. 去除冗余

删除任何无助于读者理解代码的内容：

• 重复描述代码的注释——在 counter += 1 上方写 // increment counter 就是冗余。删除。
• 冗余类型注解——如果从右侧表达式就能明显看出类型，且语言支持类型推断，则删除类型注解。
• 不必要的中间变量——如果变量只在下一行使用一次，就内联它（除非变量名确实能提升清晰度）。

只保留解释 原因 的注释——例如变通方案、限制或不明显的业务规则。这些注释很有价值。删除其他所有注释。

3. 简化逻辑

• 如果语言支持，将简单的 if/else 合并为单个表达式（如三元表达式、空合并或模式匹配）。
• 用提前退出或函数式转换（map、filter、first）替换在循环中跟踪状态的布尔标志。
• 内联足够简短且只使用一次的辅助函数。不要为只执行一次的操作提取辅助函数——相比过早抽象，保留三行相似代码更好。

4. 改进命名

• 重命名含义模糊的变量：data、result、temp、info、val、obj——这些名称无法告诉读者任何信息。使用能说明变量所代表内容的名称。
• 但对于作用域很小的临时变量（循环索引、短闭包），以及一个词就足以表达含义的情况，名称应保持简短。在 3 行的循环中使用 i 没问题。
• 遵循语言的命名约定。例如 JS/Swift 使用 camelCase，Python/Rust 使用 snake_case 等。
• 方法名称应直接描述其功能，无需注释。如果需要注释来解释方法的作用，就重命名该方法。

5. 将声明移到使用位置附近

在函数顶部定义、直到第 40 行才使用的变量，会迫使读者在脑中记住它。将声明移到首次使用之前。这样也更便于之后提取代码。

6. 拆分过长的函数

如果一个函数依次执行多个不同的任务，就将其拆分——每个部分都应各司其职，且单独阅读时也清晰易懂。对提取出的每个函数也执行上述检查。如果提取函数需要传递很多参数，或逻辑交织过深，就不要勉强拆分；应将其标记为可读性问题。

如何应用更改

1. 彻底阅读目标文件。
2. 直接完成所有更改。提高效率，批量处理相关修改。
3. 修改后，尽可能验证代码仍可编译或解析（如果项目提供 lint 或构建命令，就运行该命令）。
4. 简要列出更改——完整细节见 diff。

不要做的事

• 不要添加原先没有的注释、文档字符串或类型注解（除非重命名导致含义不明确）。
• 不要重构架构，也不要在模块之间移动文件。这是可读性优化，不是重新设计。
• 除非名称确实容易误导，否则不要更改公共 API 签名。
• 不要炫技。目标是让代码平实、直观、无需额外说明，且初次阅读也能看懂。