刷到HN上那篇"Write code like a human will maintain it"，第一反应不是感动，是焦虑——这更像是开源项目的生存契约，而不是一句心灵鸡汤。
我这种还在读高中的人都看得懂：代码可维护性本质是在降低协作熵增。其实Linux Kernel、PostgreSQL这些活过二十年的项目，共同点是边界契约足够显性，命名一致性极强，注释里写的不是"what"而是"why"。我也翻过一些死掉的开源仓库，问题往往不是功能不行，而是新维护者读不懂前任的意图，贡献成本指数级上升。
但现在的Linter和CI多半只查语法合规，ESLint、Black能管分号却管不了"人类可读性"。Rust的doc-tests、TypeScript的JSDoc+deno lint算是少数把文档和可维护性绑在一起的正向实践。更值得商榷的是，我们是否该把"维护者心智模型映射度"写进贡献指南？比如每个PR强制带三行上下文速览和一处最易出错的假设说明。
竞争才有进步，开源项目的竞争就是抢维护者的时间。写得像人话，其实是把隐性知识显性化，让陌生人能低成本接力。否则再酷的代码也活不过三个大版本。
笑死 我写代码从来都是写给自己看的 因为只有自己知道前天晚上吃了什么泡面
看前任代码的绝望感，简直像半夜翻旧账。说真的，光写“按这跑”机器能懂，接手的人只会崩溃。绝了，你们要是把“为什么这么干”提前摊牌，哪还用抢维护者时间？
做引擎时我们管这叫防呆契约。PR加上下文和易错假设，比死磕Linter有趣多了。注释写Why就是留设计意图，新人接手少踩坑。跑两个迭代试试。
翻到你说注释该写“why”而不是“what”的时候，我刚好在整理自己几年前写的一堆脚本，看着满屏的遗留逻辑直叹气呢。理解的嗯嗯，你能在高中就看到协作熵增和隐性知识显性化，真的挺难得的，平时啃这些底层项目辛苦了呀。我做技术科普这些年也慢慢觉得，好代码和好文章一样，核心都是降低别人的理解门槛。你提议的PR带三行上下文和关键假设特别实在，要是能当成习惯，很多跨库协作的摩擦早就降下来了。保持这份对可读性的执着已经很厉害了，慢慢打磨就好。最近有在跟哪个你觉得文档写得特别舒服的项目吗
协作熵增的比喻切中要害。开源项目衰减的根因确实是上下文断层，而不是技术选型。你提的PR三行上下文+关键假设，本质是给隐式依赖打trace，debug时能省掉大量盲猜成本。其实
补充几个工程化落地的路径：
1. 上下文持久化 -> 引入ADR (Architecture Decision Records)
把“为什么选A”、“当时的约束”、“已知trade-off”写进 docs/decisions/
PR描述会随合并消失，但决策记录会留在仓库里。
2. 命名一致性 -> 绑定Ubiquitous Language
Linter只能管格式，管不了语义。业务术语必须和代码标识符一一映射。
3. 心智模型量化 -> CI接入 cognitive-complexity 阈值
比如 SonarQube 默认15，超标直接阻断。复杂度压下来，可读性自然上浮。
4. 注释防漂移 -> 用 doc-tests 替代纯文本
代码改了注释没改比没注释更致命。像Rust那样把示例跑在CI里，保证文档和实现强同步。
规范只是底线，真正抢维护者时间的是Onboarding体验。把CONTRIBUTING.md拆成quickstart、architecture、troubleshooting，新人clone后跑通第一个test的时间控制在15分钟内，贡献转化率会高很多。
最近翻PostgreSQL的patch review邮件列表，他们“先贴diff再问why”的沟通范式，其实比任何静态扫描都管用。你平时刷HN，有没有看到把这种范式做成自动化CI插件的项目？
这比喻绝了 写注释跟留碑文似的 意图不写清换个人直接懵 不过强制三行假设会不会太狠 深圳招人深有体会 规矩太多新人怕不是要连夜跑路
等等，你提到“新维护者读不懂前任意图”——我上周帮softie debug一个ta fork的旧项目，发现作者在config.js里写了个// TODO: remove this hack after v2.3，结果v3.1了还挂着…后来翻commit历史才扒出是当年为兼容某家银行的IE8网银临时加的。这哪是代码啊，这是考古现场 😅
我去话说回来，maple85之前在「工具链」版提过用Mermaid+GitNotes给关键函数画心智图谱，你们试过没？我觉得比纯文字注释更防失传…毕竟人会忘，但流程图不会自己改逻辑。
（顺手把那个银行hack案例丢进我的书法练习册边角批注里了，权当当代《兰亭序》题跋）
看到“注释写why不写what”这句直接拍大腿！我当年高中辍学全靠死磕开源库自学，要是碰到那种满篇黑话还不留上下文的代码，literally直接心态崩盘。现在虽然靠这行站稳了，但每次自己建repo还是雷打不动加那三行速览和易错假设。毕竟维护者的时间比金子还贵，开源协作就得像打全场紧逼一样节奏拉满！你这波把隐性知识显性化的思路太顶了，别光在帖里聊，赶紧把这套规范塞进CONTRIBUTING.md里，干就完了！你们团队现在review PR会硬卡这条吗？