技术写作与文档2020antirez.com
编写系统软件：代码注释
Writing system software: code comments
导读
这是 Redis 作者 antirez 关于系统软件中如何写代码注释的随笔：他区分了有价值的注释与噪音，也分析了“把旧代码注释掉留在原地”这类有争议的做法。对写作者来说值得一读，因为注释的取舍与一般写作相通；核心是在正文里交代意图、背景和取舍，替读者省去猜测。
可以直接用的写作要点
- 01
说明性文字应回答“为什么这样做、放弃了什么”，不要重复“做了什么”；后者读者自己看得见。
- 02
把失败方案和走过的弯路留在文里：读者看到“这里曾经是另一种写法”，才明白现状为何如此设计。
- 03
不要指望读者去翻版本历史或旧草稿，从而自行还原你的动机；背景要显式写出来。
- 04
动笔时假定读者是几个月后的陌生人（甚至未来的自己），主动补上他不可能知道的上下文。
HN 评论精选
注释承载着版本历史传达不了的决策上下文和“此路不通”的经验，不能因为有了 Git 就一概否定。
这根本不奇怪。一项选择的后果，远不止一小段幂等代码，并非翻翻历史就能看出“这里本可以换个写法”。很多时候，某种策略或具体实现因为依赖不断变化，走过的关键实现和死胡同本身就是教学材料：周围的代码看起来又怪又浪费，直到你看到注释说明 20 个提交前这里是什么。还有“预置提交”——功能代码写好了，依赖却没就绪就要交接给别的团队，等集成等几个月是常事；把集成放在别人因内部流程拿不到的分支里，等于断了后来者的路，而注释掉并附上说明，就给他留了可循的路径。还有多少次改动没测试就上了生产？这种事天天发生。
Supermancho查看英文原文
> Finally backup comments are the ones where the developer comments older versions of some code block or even a whole function, because she or he is insecure about the change that was operated in the new one. What is puzzling is that this still happens now that we have Git. It's not puzzling _at all_. The implications of choices (which aren't limited to small blocks of idempotent code) are not a matter of reading through the history and figuring out "hey right HERE it could have been done differently". There are many points where the strategy or specific implementation (due to the flux of integrations with ever-changing dependencies) have had relevant implementations and dead-ends, which serve as a teaching tool. The surrounding code often looks strange and wasteful, until you see the comment showing what USED to be there 20 commits ago. There's also the planned commit, which is one where a functional bit of code is done and a dependency isn't ready before handoff to another team or developer. Ever had to wait for months for an integration? It happens all the time. Putting a specific integration in another branch you have access to, that may not be accessible for internal procedure reasons to someone else, leaves a developer with an obvious path forward to salvage the work - put it in the code commented out with a little teaching. How many times do you make a change and it goes to prod without tests? Happens all the time. Those kinds of places don't always have typical branch hygiene. You can label these different kinds of comments different things, but they are usually to these esoteric ends rather than "just for nostalgic 'membering".
被当成教条的写作规则（“注释是坏味道”）常被误读，需要结合具体语境加以辨析。
在跟“clean coder”们争论时，这篇文章很好用。那些人认为 Uncle Bob 反对注释，大概是误解了他的书或推文。不过，需要这样的争论本身就说明这个行业还不够成熟。
tester756查看英文原文
Handy article when arguing with "clean coders"* about comments * people who claim that UB's against them due to misunderstanding(?) his book/tweets(?), dunno. Anyway the need for those discussions is an indicator of how this industry hasn't matured yet
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选