容易混淆的问题

代码之外的很多失误，来自把两类不同的东西当成一类。下面几组区分不涉及语法，但决定了产出是资产还是噪音。

注释与文档

容易混淆	区分
注释写 what 与 why	代码能表达的不要重复，写决策和约束
没有注释与过时注释	过时注释更危险，读者会先相信它
安装与用法	读者先看用法再决定要不要装
固定链接与行号链接	行号随代码漂移，用 tag 或 commit hash
文档与代码	二者同属一个变更，改接口就改示例
注释数量与代码质量	注释多不等于清晰，可能只是代码没写好
文档长度与有用程度	长文档没人读完，短而准的文档更容易被维护

判断标准是删掉之后读者会损失什么。删掉重复代码的注释毫无损失，删掉「为什么不用显而易见的写法」可能让后人把问题改回来。

文档也有同样的检验方式：把 README 给一个没用过项目的人看，观察他在哪一步停下来提问。停下来的位置就是文档缺信息的位置。

提交与协作

容易混淆	区分
一个提交与一个 PR	提交是回滚单位，PR 是评审单位
向上游贡献与 fork	fork 适合方向不合或上游已停止维护
issue 与聊天消息	issue 要能独立复现，不依赖上下文
阻塞意见与个人偏好	只有正确性、安全、数据问题该拦合并
补充信息与 me too	前者提供新线索，后者只增加未读

把重构和新功能塞进一个提交，回滚时会带走不相关改动，git bisect 也只能定位到一团混合变更。同理，把无关修复塞进一个 PR，reviewer 无法判断哪一部分导致了行为变化。

PR 描述里的 why 不能省。维护者接受 PR 等于接手长期维护，他需要知道你解决了什么问题、为什么选这个方案。

沟通与 AI

容易混淆	区分
说出理解与直接问	前者让回答者定位偏差，不用从头讲
XY 问题与真实目标	描述目标，而不是自己设想卡住的解法
披露 AI 与隐瞒	披露决定审查强度，隐瞒把风险留给别人
AI 初审与人工评审	前者不懂产品约束，会自信地给出错误建议
生成速度与审查成本	省下的是打字时间，不是判断时间
工具熟练与领域理解	会调模型不等于会解决问题

# 弱
update parser

# 强
fix: 解析空单元格时不再吞掉后续列

问题：CSV 末尾空列被跳过，导致行长度不一致。
方案：保留空字段，按表头长度补齐。
影响：下游按索引取值的代码需要处理空字符串。

两种提交都能通过编译，区别在于半年后还有没有人能还原当时的判断。沟通也是同一件事：留下判断依据，而不是只留下结论。

读者是谁

同一份材料会被三类人读到：半年后的自己、刚加入的同事、项目外部的使用者。三类人掌握的背景依次减少，对信息完整度的要求依次提高。

读者	先看什么	需要得到什么
未来的自己	注释与提交信息	当时的约束和取舍
新同事	README 与开发文档	跑起来的最短路径
外部用户	README 顶部与示例	能否解决他的问题

写作时轮流扮演这三种读者，比套用模板有效。模板保证结构完整，读者视角保证内容有用。

同一个事实对不同读者要写不同深度。内部实现细节放注释，使用约束放文档，项目定位放 README；放错位置的信息，等于没写。