软件开发规则

代码质量

• 可读性好的代码胜过精巧的代码——你阅读代码的次数会是编写代码的十倍
• 函数应只做一件事——如果需要用“和”来描述其功能，就把它拆分
• 根据功能而非实现方式命名——实现会变，目的不变
• 删除无用代码——版本控制系统会记住，代码库不应背负负担
• 风格一致性比选择哪种风格更重要——与项目保持一致

调试

• 完整阅读错误信息——答案往往就在其中
• 修复前先复现——如果不能触发问题，就无法验证修复
• 二分法排查：注释掉一半代码来定位问题所在的那一半
• 先检查明显问题——拼写错误、错误文件、缓存过期、环境配置错误
• 遇到瓶颈时大量打印/记录日志——假设通常是错误的

测试

• 测试行为而非实现——重构时测试不应中断
• 尽可能每个测试只做一个断言——失败时能准确定位问题
• 将测试命名为描述预期行为的句子——可读的测试名称本身就是文档
• 模拟外部依赖，而非内部逻辑——集成点是边界
• 快速测试频繁运行，慢速测试选择性跳过——为反馈速度优化

错误处理

• 快速失败并明确报错——静默失败会制造调试噩梦
• 捕获特定异常，而非笼统捕获——不同错误需要不同处理
• 记录足够上下文以便调试——仅有错误类型是不够的
• 面向用户的错误信息应有帮助性——“出了点问题”对任何人都没有帮助
• 不要捕获你无法处理的异常——让它们向上传递

架构设计

• 从简单开始，需要时再增加复杂性——过早抽象是浪费时间
• 关注点分离——UI、业务逻辑、数据访问是不同的职责
• 依赖关系向内流动——核心逻辑不应了解框架细节
• 配置与代码分离——环境相关值外部化
• 记录决策过程，而不仅仅是代码——原因比内容更重要

代码审查

• 检查代码时注重理解，而非仅仅纠错——如果连你自己都看不懂，别人更无法理解
• 用提问代替命令——以“如果...”开启讨论
• 精简的代码变更请求更易获得有效反馈——500行代码只能被略读，50行代码才会被细读
• 达到良好即可批准，不必追求完美——进展比完美更重要
• 优先发现程序错误，代码风格问题次之——分清主次关系

性能优化

• 优化前先测量——对性能瓶颈的直觉判断往往是错误的
• 聚焦热点路径优化——90%的运行时间消耗在10%的代码上
• 数据库查询通常是性能瓶颈——优先检查此处
• 缓存能解决许多问题——但缓存失效机制会带来新难题
• 过早优化徒耗时间——先确保可用，再追求高效

依赖管理

• 引入前先评估——每个依赖都是不可控的外部代码
• 锁定版本号——“最新版”会不可预测地破坏构建
• 检查维护状态——被遗弃的软件包会形成安全隐患
• 依赖越少越好——每个依赖都会增加供应链风险
• 升级前阅读变更日志——破坏性变更可能隐藏在次要版本中

在现有代码库中工作

• 遵循现有模式——一致性优于个人偏好
• 渐进式改进——践行童子军法则，让代码比接手时更好
• 修改前先理解——阅读测试用例，检查Git历史记录
• 修复错误时不要重构——分离提交，分离拉取请求
• 遗留代码能运行——尊重历史战斗痕迹

沟通协作

• 提交信息要解释原因而非现象——差异对比会展示具体改动
• 记录异常行为——未来的开发者需要了解背景
• 重大重构前先沟通——达成共识可避免无用功
• 用区间而非单点估算工期——“2-4天”比“3天”更真实
• 不懂时就说“我不知道”——猜测会浪费所有人的时间