技术写作与文档2018antirez.com编辑精选
编写系统软件：代码注释
Writing system software: code comments
导读
这是 Redis 作者 antirez 关于系统软件中代码注释的写作心得：注释不该复述代码在做什么，而要交代意图、背景和取舍，也就是回答“为什么”。对写作者来说，它把说明性写作的几个基本问题讲得很具体：命名是否清晰、结构如何分段、读者需要的上下文由谁来补。
可以直接用的写作要点
- 01
注释写“为什么”而不是“做什么”：代码本身已经说明了 what，注释要交代意图、权衡和背景。
- 02
用“段落标题”式注释给长文件分段，相当于在文件内部做结构划分，让读者知道自己在哪一部分。
- 03
命名含混再靠注释补救，等于把理解成本转嫁给读者；先把概念框架想清楚，词汇自然就清楚。
- 04
说明性文字要有单一归属：散落在网盘文档、Markdown、表格、邮件里的注释等于没有注释。
HN 评论精选
团队对注释与文档的态度，是判断工程文化是否健康的可靠信号。
面试时我会问：这个团队和工程组织对代码注释持什么立场，遗留代码的文档处于什么状态。这个问题很好用，因为人们会用“知识产权保护”之类的借口回避谈论真实代码的糟糕现状，但只问注释和文档，他们就没有合理的理由闪躲；不肯回答，本身就是答案。凡是持“代码应当自解释”态度的地方，我直接走人——那是一种你解决不了的机能失调。说“我们一直在探索改进文档实践的新方法”的地方，也得继续追问具体细节。多数工作我都知道自己要面对糟糕的遗留代码，但如果同时还存在不写文档、反对注释和规范化的 API/函数文档的文化，结果是 Google Docs、Markdown 文件、表格、邮件、Confluence 页面满天飞的“文档意面”，那就没意义了，我帮不了你。
mlthoughts2018查看英文原文
When I interview for jobs, one of the questions I ask is where the team and engineering org stand on code comments and what state of documentation do they have for legacy code. It's a good question because people will use excuses like IP protection to avoid talking about the ugly truth of the state of their actual code, but if you're just asking about comments and documentation, there's no reasonable way they can deflect the question. If they won't answer it, well, you've got your answer. Any place that takes an attitude of "code should be self-documenting" I just walk away from. That is a type of dysfunction you're not gonna be able to solve. Also places that say, "we're always evaluating new ways to improve documentation practices..." begs further questions to get the specifics out of them. For most jobs, I know I'm going to have to deal with bad legacy code. But if there is also a culture of not documenting things, arguing against comments or formatted API and function documentation, and it results in documentation spaghetti of Google docs, Markdown files, spreadsheets, emails, confluence pages, etc., then there's no point. I can't help you.
用注释充当段落标题，是在单个文件内部做结构分层。
我在这里缺的一类注释是“段落标题”。我习惯把文件组织成段落甚至几段一组，常用“段落标题”来区分，本质上是在多个文件之间拆分的一种弱化版本。比如我在写一个很简单的预处理器，把它分成四段：第一段不加标记，呈现公共接口；接着是一段用注释“Lexer”标记；再后面用注释“Parser”标记；最后一段标记为“TURN BLOCK BACK INTO TEXT”，这个大概该改成“处理解析结果”之类。有时我的代码“段落”前面也会有一行短注释，说明整段在做什么，我想那大致属于“引导性注释”。
rocqua查看英文原文
A type of comment I miss here are "section headers". I tend to organize my files into paragraphs or even sections of paragraphs. I often use "section headers" to distinguish these. It is essentially a weaker version of splitting a file across multiple files. For example, I am working on a very simple pre-processor, and I have split it into 4 sections. The first is unmarked and presents the public interface. After that is a section marked simply by the comment "Lexer", after that is a section marked by the comment "Parser", and finally there is a section marked "TURN BLOCK BACK INTO TEXT". That last one should probably be changed to something like "Process result of parsing". Sometime, my 'paragraphs' of code also get a short line comment explaining what the entire paragraph does. I guess that would generally fall under the 'guide comment' category.
命名混乱靠注释补救，是把阅读成本转嫁给读者，也暴露了概念框架的缺失。
我宁愿要命名良好的变量、函数和类，也不要代码注释。读那种作者出于某些想不通的理由，把变量名缩写成难以辨认的缩写、首字母组合和让人抓头的单字母的代码，真是苦差事。在注释和代码之间来回切换，对作者也许轻松，对读者却不友好。而且这种爱用短变量名的倾向，往往指向一个更糟的问题：作者没有在高层面深入思考过这个软件，因此没有围绕问题空间形成好的词汇和概念框架。
apo查看英文原文
I'll take well-named variables, functions, and classes over code comments any day. It's a chore and and half to plow through code in which the author has, for whatever misguided reasons, shortened variable names to inscrutable abbreviations, acronyms, and single letter head-scratchers. Context-switching between comments and code may be easy for the author, but isn't good for the reader. More often than not, the short-variable tendency points to an even worse problem: the author hasn't though very deeply about the software at a high level and therefore hasn't developed a good vocabulary or conceptual framework around the problem space.
代码说明“做什么”，注释承担“为什么”，意图不会自动从代码里显现。
非常感谢这篇文章。开发者自认为自己的代码是神赐之物、人人都能看懂，并不等于事实如此。代码是 what，注释是 why；你不能指望开发者的意图仅凭代码自己浮现出来。
threeseed查看英文原文
Thank you so much for this article. Just because a developer thinks their code is a gift from the gods and understandable by all doesn’t make it true. Code is the what. Comments are the why. You can’t expect the developer’s intent to come out through the code alone.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选