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（不要重复自己）：无重复代码
YAGNI（你不会需要它）：不要为假设的未来而构建
KISS（保持简单）：避免不必要的复杂性
童子军规则：让代码比你发现时更干净

需要避免的代码坏味道

过长的函数或类
重复代码
死代码（未使用的变量、函数、参数）
特性嫉妒（方法对其他类更感兴趣）
不恰当的亲密关系（类之间了解太多彼此的内部）
过长的参数列表
基本类型偏执（过度使用基本类型而非小对象）
Switch/case 语句（考虑使用多态）
临时字段（类变量只在某些时候使用）

并发

将并发代码与其他代码分离
限制同步/锁定数据的范围
使用线程安全的集合
保持同步代码段尽量小
了解你的执行模型和原语

系统设计

将构造与使用分离（依赖注入）
使用工厂模式、建造者模式创建复杂对象
面向接口编程，而非面向实现编程
优先使用组合而非继承
在设计模式能简化代码时使用，而非为了炫技

重构

持续重构，而非大批量重构
重构前后始终确保测试通过
小步前进：每次只做一个改动
常见重构：提取方法、重命名、移动、内联

文档

自文档化代码 > 注释 > 外部文档
公共 API 需要清晰的文档
文档中包含示例
让文档靠近代码（最好在代码中）

核心理念：代码的阅读次数是编写次数的 10 倍。优化可读性和可维护性，而非追求巧妙。