编码风格

不可变性（关键）

始终创建新对象，永不修改已有对象：

// 伪代码
错误：modify(original, field, value) → 原地修改 original
正确：update(original, field, value) → 返回包含变更的新副本

原因：不可变数据防止隐藏副作用，使调试更简单，并支持安全并发。

核心原则

KISS（保持简单）

• 优先选择确实有效的最简单方案
• 避免过早优化
• 优先清晰而非巧妙

DRY（避免重复）

• 将重复逻辑提取为共享函数或工具
• 避免复制粘贴导致的实现漂移
• 当重复真实存在而非假设性时引入抽象

YAGNI（不做无用功）

• 不要提前构建不需要的功能或抽象
• 避假设性泛化
• 从简单开始，当压力真实存在时再重构

文件组织

多小文件 > 少大文件：

• 高内聚，低耦合
• 通常 200-400 行，最多 800 行
• 从大模块提取工具函数
• 按功能/领域组织，而非按类型

错误处理

始终全面处理错误：

• 每一层都显式处理错误
• UI 代码中提供用户友好的错误消息
• 服务端记录详细的错误上下文
• 永不静默吞掉错误

输入验证

始终在系统边界验证：

• 处理前验证所有用户输入
• 尽可能使用基于 Schema 的验证
• 快速失败并给出清晰错误消息
• 永不信任外部数据（API 响应、用户输入、文件内容）

命名规范

• 变量和函数：camelCase，使用描述性名称
• 布尔值：优先使用 is、has、should 或 can 前缀
• 接口、类型和组件：PascalCase
• 常量：UPPER_SNAKE_CASE
• 自定义 hooks：camelCase 带 use 前缀

需避免的代码异味

深层嵌套

当逻辑开始堆叠时，优先使用提前返回而非嵌套条件。

魔法数字

为有意义的阈值、延迟和限制使用命名常量。

长函数

将大函数拆分为职责清晰的片段。

代码质量清单

标记工作完成前：

• 代码可读且命名良好
• 函数小巧（<50 行）
• 文件聚焦（<800 行）
• 无深层嵌套（>4 层）
• 错误处理得当
• 无硬编码值（使用常量或配置）
• 无可变性（使用不可变模式）