软件开发规范

代码质量

• 可读性优于巧妙性——你阅读代码的次数远超编写次数（约10倍）
• 函数只做一件事——若需用“和”来描述其职责，就应将其拆分
• 按功能命名，而非实现方式——实现可能变更，而目的保持不变
• 及时删除无效代码——版本控制系统已记录历史，代码库不应承载冗余负担
• 风格一致性比具体风格选择更重要——始终遵循项目既定规范

调试

• 完整阅读错误信息——答案往往就藏在其中
• 先复现问题再修复——无法触发的问题，便无法验证是否真正修复
• 二分法排查：注释掉一半代码，快速定位问题所在区间
• 优先检查明显问题——拼写错误、文件路径错误、缓存未更新、环境配置错误等
• 卡住时大胆打印/记录日志——多数假设其实并不成立

测试

• 测试行为，而非实现细节——重构时测试不应失败
• 尽可能做到每个测试仅含一个断言——失败时可精确定位问题根源
• 测试名称应为完整句子，清晰描述预期行为——可读性强的测试名本身就是文档
• 对外部依赖进行 Mock，而非内部逻辑——集成点即为边界
• 快速测试应高频运行，慢速测试可被跳过——优先保障反馈速度

错误处理

• 快速且明确地失败——静默失败将极大增加调试难度
• 捕获具体异常类型，而非泛化异常——不同错误需差异化处理
• 记录足够上下文用于调试——仅记录错误类型远远不够
• 面向用户的错误提示应具备实用性——“出错了”对任何人都无帮助
• 不捕获无法处理的异常——让其自然向上抛出

架构设计

• 从简单开始，按需引入复杂度——过早抽象只会浪费时间
• 关注点分离——UI、业务逻辑与数据访问属于不同职责范畴
• 依赖关系应向内流动——核心逻辑不应感知框架细节
• 配置与代码分离——环境相关参数需外部化管理
• 记录决策依据，而不仅是代码本身——“为什么这么做”比“做了什么”更重要

代码审查

• 审查目标是理解，而不仅是正确性——若你难以理解，他人亦然
• 多提问题，少下指令——例如“如果……会怎样？”可有效开启讨论
• 小规模 PR 更易获得高质量审查——500 行易被略读，50 行才真正被细读
• 达到“足够好”即可批准，不必追求完美——进展优于尽善尽美
• 优先发现缺陷，风格问题次之——主次须分明

性能优化

• 先测量，再优化——关于性能瓶颈的直觉通常并不可靠
• 聚焦热路径优化——90% 的执行时间往往消耗在 10% 的代码上
• 数据库查询通常是瓶颈所在——排查时应优先检查此处
• 缓存能解决许多问题——但缓存失效机制又会引发新挑战
• 避免过早优化——先确保功能可用，再考虑性能提升

依赖管理

• 引入前务必评估——每个依赖都是你无法掌控的代码
• 锁定依赖版本——使用 “latest” 将导致构建结果不可预测
• 核查维护状态——已被弃用的包将成为安全风险源
• 依赖数量越少越好——每个新增依赖都会扩大供应链攻击面
• 升级前必读变更日志——破坏性变更常隐藏于次要版本中

在现有代码库中工作

• 遵循既有模式——一致性优先于个人偏好
• 渐进式改进——践行“童子军规则”，离开时让代码比来时更优
• 先理解，再修改——阅读测试用例，查阅 Git 历史记录
• 修复 Bug 时不进行重构——拆分为独立提交与独立 PR
• 遗留代码仍在运行——请尊重其历经考验所留下的痕迹

沟通协作

• 提交信息说明“为什么”，而非“做了什么”——变更内容由 diff 展示
• 为反直觉行为补充文档——后续开发者需要上下文支持
• 大规模重构前先沟通对齐——避免因方向偏差造成返工
• 估算任务耗时采用区间形式，而非单点值——“2–4 天”比“3 天”更诚实可信
• 不知道就说“我不知道”——随意猜测只会浪费所有人的时间