技术写作与文档2022naturaldocs.org
NaturalDocs：用平实英语编写代码文档
NaturalDocs: Plain English code documentation
导读
这篇是 NaturalDocs 的入门文档，讲如何用近似自然英语的方式为代码写说明文档，并给出注释格式示例。评论区围绕“注释该写多少、要不要重复函数名和类型”展开争论，对任何写说明性文字的人都有借鉴：文档的价值在于补充代码没说的信息，而不是复述已有内容。
可以直接用的写作要点
- 01
别在注释里重复函数名和参数类型等代码本身已写明的信息，把篇幅留给代码说不出的意图和原因。
- 02
把解释放在离代码最近的地方，避免同一件事要在两个位置维护，否则迟早忘记同步更新。
- 03
让命名承担一部分说明职责：好的函数名和参数名能让调用处自解释，减少注释负担。
- 04
注释应当短于它描述的代码，如果一段注释比函数本身还长，说明该拆分或重命名代码了。
HN 评论精选
注释不应复制代码签名里已有的信息，只写增量说明。
一个批评是：写文档时函数名和类型明明就在下面，却还要在注释里重复一遍，比如先写“Function: Multiply / 把两个整数相乘并返回结果”，再写 int Multiply(int x, int y)。相比之下 JSDoc 直接利用代码本身，只写一句“把两个整数相乘并返回结果”就够了，不必重复名称。如果我没理解错项目意图，我建议加上这个特性。
rendall查看英文原文
One critique is that the documenting must duplicate the name and type when it's right there. e.g. // Function: Multiply // Multiplies two integers and returns the result. int Multiply (int x, int y) { return x * y; } JSDoc, by contrast, uses the code itself and it's not necessary to duplicate the name. /** Multiplies two integers and returns the result. */ int Multiply (int x, int y) { return x * y; } I might recommend the addition of this feature, if I understood the intent of the project correctly.
注释式文档语言导致重复劳动和代码文档脱节，不如靠命名和语言语法自解释。
我讨厌这种“在注释里实现一门语言”的做法，JSDoc 也是。它们逼你写更多注释代码（有时注释比函数本身还长），逼你重复自己，只是多了一点点信息却换了一套语法，而且这套语法还没有语法检查和语法高亮。它们把代码和文档割裂开：哪怕就在旁边，改两个地方也很烦，而且可能忘了更新注释。我能接受只抓取纯文本注释的工具，最多用一个极短的标记来开关某条注释。我更希望语言本身允许把这类元数据写进语法，让解释自然出现在需要的地方。Objective-C 有一点很好：函数声明本身就说明了一切，比如 Multiply:with:，调用时写成 Multiply: 23 with: 3，参数含义一目了然，前提是作者在命名上稍微用点心。
dusted查看英文原文
I hate these "languages implemented in comments" jsdoc is another one. They force you to write more comment code (sometimes the comment will be longer than the actual function), they force you to repeat yourself, but with ever so slightly more information and different syntax (but this time, forget about syntax checking or highlighting!). They disconnect actual code from the documentation, even if they're "right there next to it" it's annoying to have to edit two different places, and possible to forget to update the comment. I'd probably accept one that scrapes comments, but has no syntax, except maybe something _VERY_ short to enable/disable the scraping of an individual comment. I'd prefer it if the language allowed me to write this metadata directly into the syntax, so that it is natural flow to include the explanations where they are needed. One thing I found interesting and nice about Objective-C syntax was the way function declarations made them self-explanatory. You never needed think twice about what the parameter was for (assuming the function author did a slight effort in naming). (int) Multiply: (int)x with: (int)y result = Multiply: 23 with 3; (int) Subtract: (int)a from: (int)b andMultiplyBy: (int)c result = Subtract: 1 from: 4 and MultiplyBy: 2;
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选