代码是写给未来的讯息
核心论点：代码即沟通
工程师无时无刻不在沟通。Slack、设计文档、RFC、代码评审批注——这些渠道都得到重视；唯独代码本身这条沟通渠道常常被忽略。代码不只是给机器执行的指令，更是写给下一个需要阅读、扩展或调试它的工程师的讯息：评审人员、六个月后的自己。一条提交信息就是一条必须独立存在的 Slack 消息——没有对话上下文，无法追问补充，通常在写下数年后才会被阅读。
一旦把代码视为沟通媒介，问题就变了：这条提交记录能否独立看懂？有人能否顺着逻辑评审这个合并请求？这段注释是在阐释代码的设计初衷，还是仅仅复述了代码本身的行为？本地工作流是自己的事，可以反复试错；但代码一旦准备合并，它就成为代码库的组成部分——有人会依靠它弄清楚修改缘由、故障引入节点，以及这份合并请求意在解决何种问题。
关键隐喻：PR 是一个故事
一个实用的思考方式：把合并请求比作一本书，每一次代码提交就是一个章节，提交中的代码改动是正文。没人会随意跳页看书，评审人员按提交顺序查看代码时应当能顺理清作者的思路，无需凭空揣测，也不用一次性记住全部改动才能看懂其中任意片段。
实践中的例子是五步提交序列：① 为接口新增搜索端点；② 实现基础相关性排序功能；③ 将排序逻辑抽象为独立模块；④ 编写排序单元测试；⑤ 编写搜索接口集成测试。按顺序看完这五条记录，故事脉络就自然浮现——不需要借助 PR 描述来复盘这个过程，提交本身就在讲述这一切。
实践启示
原子化提交：想要实现"读提交即读故事"的效果，每一笔提交都要具备独立意义。一次重命名加一次行为改变不是一件事，是两个独立的改变，通常应分成两个独立提交。提交标题和章节内容同等重要，提交说明本身需要自带必要的上下文信息。像「修复 ABC-123」这种消息只是指向了外部的上下文，日后他人查阅时，对应的外部上下文或许已经无法获取到。
评审中追加而非重写：在进行评审时，切勿在沟通未结束时强制推送并重写提交历史——评审人员的评论会锚定到特定的行；保留原始故事，在其基础上新增提交处理反馈，后续任何人都能准确看到这个 PR 是如何演变的。
注释要解释 Why 而非 What：代码本身已经展示了行为逻辑，但往往无法说明代码存在的原因、限制条件以及隐含的预设逻辑。// 计数器自增 这样的注释毫无意义，而 // 必须在订阅创建前执行，否则回调会在状态就绪前触发 则是关键说明文档——能节省数小时的调试时间，从根源上规避潜在缺陷。
结构即信息：清晰的章节结构本身就是信息传递，如果做得好，读者就永远不需要去猜测其中的含义。好的提交说明、结构清晰的合并请求同理。
AI 编码时代的新要求
AI 智能体让"写给未来讯息"变得更重要，而不是更不重要——尽管表面上 AI 让代码生成效率大增，但后期整理修复的成本远超团队预期的提速收益。如果放任 AI 自主输出，最终只会生成一个巨大的提交，附带一条"实现功能"的提交信息，没有任何关于背后推理的痕迹。让 AI 智能体遵循和人类工程师相同的规范就能改变这种状况：原子化提交能让 AI 的设计思路清晰可读——能看清它先构建了什么、在哪里重构了、编写了哪些测试以及整体实现顺序。这不仅有助于理解代码，还能在缺陷上线前提前发现 AI 逻辑中的疏漏。如果一条提交直接从"新增接口"跳到"新增集成测试"，中间缺少过渡步骤，这本身就是一个风险信号——条理清晰的提交记录具备可审计性，这是单一杂乱的代码变更无法实现的。
我的判断（前端工程师视角）
在 AI 编码时代，"写给未来的讯息"在前端工程语境下被赋予了新的具体含义：
- 变量命名与组件边界：React 组件的 props/state 命名、custom hook 拆分粒度，本质上是为未来的"读者"（同事、AI 工具）写的产品语义注释。
data、item这样的命名在 AI 自动补全时代尤其危险——它会沿着模糊语义继续生成更难读的代码。 - commit message 与 PR 描述：前端项目合并频繁、PR 普遍偏大（一次合十几个组件是常态），更需要按"故事章节"拆分。
feat: add searchvsfeat(search): add endpoint / refactor: extract sort util / test: add sort unit + integration的差别，决定了未来读者是否能在 5 分钟内理解意图。 - AI 提示词即新型注释：当用 Cursor / Copilot 生成代码时，prompt 本身就是设计意图的载体。建议把关键 prompt 沉淀在 PR 描述或
// generated-by:注释里，让"为什么这样写"不只存在于一次性的对话框中。 - 类型即文档：TypeScript 类型 + JSDoc 在 AI 时代反而是更高效的"沟通媒介"——它们是结构化的、可被 AI 解析的、不会被生成代码覆盖掉的契约层。
归根结底，代码可读性在 AI 时代不是退居次要，而是升级为"人机协作的可审计性"——它是人类意图与机器输出之间唯一可控的契约。