mirror of
https://github.com/luongnv89/claude-howto.git
synced 2026-04-26 09:56:01 +02:00
Luong NGUYEN
89e89d4aa3
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# 面向 AI 代码生成的整洁代码规则
|
||
|
||
这些规则用于指导代码生成，帮助产出可维护、专业水准的代码。
|
||
|
||
## 有意义的命名
|
||
- 使用能体现意图的名称，说明它为什么存在
|
||
- 避免误导性命名和无意义区分，例如 `data`、`info`、`manager`
|
||
- 使用可读、可搜索的名称
|
||
- 类名使用名词，例如 `UserAccount`、`PaymentProcessor`
|
||
- 方法名使用动词，例如 `calculateTotal`、`sendEmail`
|
||
- 避免脑内映射和编码风格命名，例如匈牙利命名法、前缀
|
||
|
||
## 函数
|
||
- 保持函数短小精炼，理想情况下少于 20 行
|
||
- 只做一件事，遵循单一职责原则
|
||
- 每个函数只处理一个抽象层级
|
||
- 限制参数数量，理想为 0-2 个，最多 3 个，避免布尔标志参数
|
||
- 不要产生副作用，函数应该做它名字所说的事
|
||
- 将命令与查询分离，命令修改状态，查询返回信息
|
||
- 优先使用异常而不是错误码
|
||
|
||
## 注释
|
||
- 代码本身应该尽量可自解释，能不写注释就不写
|
||
- 好的注释包括：法律信息、警告、TODO、公共 API 文档
|
||
- 坏的注释包括：重复、误导，或者只是解释糟糕的代码
|
||
- 不要注释掉代码，直接删除，版本控制会保留历史
|
||
- 如果你需要写注释，先考虑重构代码
|
||
|
||
## 格式化
|
||
- 保持文件小而聚焦
|
||
- 垂直格式化：相关概念放近一些，空行分隔不同概念
|
||
- 水平格式化：限制行长度在 80-120 个字符之间
|
||
- 使用一致的缩进和团队风格
|
||
- 将相关函数分组放在一起
|
||
|
||
## 对象与数据结构
|
||
- 对象：通过抽象隐藏数据，通过方法暴露行为
|
||
- 数据结构：暴露数据，尽量少提供行为
|
||
- 迪米特法则：只和直接朋友说话，避免 `a.getB().getC().doSomething()`
|
||
- 不要毫无节制地通过 getter/setter 暴露内部结构
|
||
|
||
## 错误处理
|
||
- 使用异常，不要使用返回码或错误标志
|
||
- 代码可能失败时，先写 `try-catch-finally`
|
||
- 在异常信息中提供上下文
|
||
- 不要返回 `null`，改为返回空集合或使用 Optional/Maybe
|
||
- 不要把 `null` 作为参数传入
|
||
|
||
## 类
|
||
- 小类应按职责衡量，而不是按行数衡量
|
||
- 单一职责原则：只有一个改变原因
|
||
- 高内聚：类变量被多数方法使用
|
||
- 低耦合：类之间依赖尽量少
|
||
- 开闭原则：对扩展开放，对修改关闭
|
||
|
||
## 单元测试
|
||
- 快速、独立、可重复、自我验证、及时（F.I.R.S.T.）
|
||
- 每个测试一个断言，或只验证一个概念
|
||
- 测试代码质量应与生产代码质量一致
|
||
- 测试名称要可读，清楚描述正在测试什么
|
||
- 遵循 Arrange-Act-Assert 模式
|
||
|
||
## 代码质量原则
|
||
- **DRY（Don't Repeat Yourself）**：不要重复
|
||
- **YAGNI（You Aren't Gonna Need It）**：不要为假设中的未来提前构建
|
||
- **KISS（Keep It Simple）**：避免不必要的复杂度
|
||
- **童子军规则**：让代码比你接手时更干净
|
||
|
||
## 应避免的代码坏味道
|
||
- 函数或类过长
|
||
- 重复代码
|
||
- 死代码（未使用的变量、函数、参数）
|
||
- 特性依恋（方法更关心别的类）
|
||
- 不恰当的亲密关系（类彼此了解过多）
|
||
- 过长的参数列表
|
||
- 原始类型偏执（过度使用原始类型而不是小对象）
|
||
- switch/case 语句（考虑使用多态）
|
||
- 临时字段（类变量只在某些时候才使用）
|
||
|
||
## 并发
|
||
- 将并发代码与其他代码隔离
|
||
- 限制同步/加锁数据的作用域
|
||
- 使用线程安全集合
|
||
- 保持同步区块尽量小
|
||
- 了解你的执行模型和原语
|
||
|
||
## 系统设计
|
||
- 将构建和使用分离，例如通过依赖注入
|
||
- 复杂对象创建时使用工厂、构建器
|
||
- 面向接口编程，而不是面向实现编程
|
||
- 优先组合而不是继承
|
||
- 设计模式只在它们简化问题时使用，不要为了炫技而使用
|
||
|
||
## 重构
|
||
- 持续重构，不要攒成大批量一次做完
|
||
- 重构前后都要保证测试通过
|
||
- 小步前进，每次只改一处
|
||
- 常见重构包括：提取方法、重命名、移动、内联
|
||
|
||
## 文档
|
||
- 自说明代码 > 注释 > 外部文档
|
||
- 公共 API 需要清晰文档
|
||
- 文档中要包含示例
|
||
- 文档尽量靠近代码，理想情况下就在代码里
|
||
|
||
---
|
||
|
||
**核心理念**：代码被阅读的次数是编写次数的 10 倍。优化可读性和可维护性，而不是追求花哨。
|