clean-code

# Clean Code - 务实 AI 编码标准 > **关键技能** - 保持 **简洁、直接且专注于解决方案**。 --- ## 核心原则 | 原则 | 规则 | |-----------|------| | **SRP** | 单一职责 - 每个函数/类只做一件事 | | **DRY** | 不要重复自己 - 提取重复代码，复用 | | **KISS** | 保持简单 - 使用最简单的有效方案 | | **YAGNI** | 你不会需要它 - 不要构建未使用的功能 | | **童子军规则** | 让代码比你发现时更整洁 | --- ## 命名规则 | 元素 | 约定 | |---------|------------| | **变量** | 揭示意图：使用 `userCount` 而非 `n` | | **函数** | 动词 + 名词：使用 `getUserById()` 而非 `user()` | | **布尔值** | 问题形式：`isActive`, `hasPermission`, `canEdit` | | **常量** | 全大写蛇形命名：`MAX_RETRY_COUNT` | > **规则：** 如果你需要注释来解释一个名称，请重命名它。 --- ## 函数规则 | 规则 | 描述 | |------|-------------| | **短小** | 最多 20 行，理想为 5-10 行 | | **单一职责** | 只做一件事，且做得很好 | | **单一抽象层** | 每个函数保持单一抽象层级 | | **参数少** | 最多 3 个参数，优先 0-2 个 | | **无副作用** | 不要意外地修改输入 | --- ## 代码结构 | 模式 | 应用 | |---------|-------| | **卫语句** | 针对边界情况尽早返回 | | **扁平 > 嵌套** | 避免深层嵌套（最多 2 层） | | **组合** | 将小函数组合在一起 | | **并置** | 将相关代码放在一起 | --- ## AI 编码风格 | 情况 | 行动 | |-----------|--------| | 用户要求功能 | 直接编写 | | 用户报告 Bug | 修复它，不要解释 | | 无明确需求 | 询问，不要假设 | --- ## 反模式（请勿使用） | ❌ 模式 | ✅ 修复 | |-----------|-------| | 为每一行写注释 | 删除显而易见的注释 | | 为单行代码写辅助函数 | 内联代码 | | 为 2 个对象写工厂模式 | 直接实例化 | | 包含 1 个函数的 utils.ts | 将代码放在使用处 | | “首先我们导入...” | 直接写代码 | | 深层嵌套 | 使用卫语句 | | 魔术数字 | 使用命名常量 | | 神级函数 | 按职责拆分 | --- ## 🔴 编辑任何文件前（先思考！） **修改文件前，问自己：** | 问题 | 原因 | |----------|-----| | **什么导入了这个文件？** | 可能会破坏依赖 | | **这个文件导入了什么？** | 接口变更影响 | | **什么测试覆盖了它？** | 测试可能会失败 | | **这是一个共享组件吗？** | 会影响多个地方 | **快速检查：** ``