技术写作与文档2015gpfault.net
如何写好关于指针所有权的注释
Writing comments about pointer ownership
导读
这篇短文讨论在 C++ 代码里如何用注释说明指针的所有权：谁分配、谁释放、谁只是借用。作者关心的是，怎样把这类信息写得让接手代码的人一眼看懂。对写作者来说，它提供了一个很好的案例：当信息既可以用注释解释，也可以由形式本身（类型、签名、命名）承载时，该怎么取舍，以及为什么注释会随时间失效。
可以直接用的写作要点
- 01
注释应回答“为什么”和“谁负责”，比如说明谁拥有这块内存、谁负责释放，而不是复述代码在做什么。
- 02
优先让形式本身传达意图（类型、函数签名、命名），注释只补充机器无法表达的那部分信息。
- 03
把关键动作明写出来，例如在调用处写出 std::move，等于给读者一个“这里发生了所有权转移”的信号，不要让读者自己去猜。
- 04
假定读者是几年后接手的人：人员流动会让注释与代码脱节，所以注释要紧贴代码、随改随更新，或者干脆用类型和工具替代它。
HN 评论精选
让调用处显式写出转移动作，等于把意图写给读者看；安全保证应交给语言机制，而不是靠注释。
有人可能会问，为什么我把 BlackBox::store 的参数写成右值引用，而不是左值引用、强迫调用方使用 std::move。左值引用其实也能用，但那样就写不出 crate.store(std::make_unique<Gadget>(beeper, flasher)); 这样的代码了。我也认为强迫调用方在调用处写 std::move 是好事而非坏事，因为它把预期的效果传达给了读者。这里按值传递 unique_ptr 才是正确选择，它完全能接受临时对象。而在我看来，如果你想要那样的安全保证，就该用 Rust。我以前是 C++ 新标准的粉丝，用了一段时间后却觉得 C 是更舒服的语言：写“地道的 C++”心智负担太重，有时遇到的编译错误纯粹是浪费开发者的时间。
merogin查看英文原文
Some people might ask why I chose to make the parameter of BlackBox::store an rvalue reference rather than an lvalue reference and force the client code to use std::move. While it is true that an lvalue reference would also have worked, if I did that, it would be impossible to write code like crate.store(std::make_unique<Gadget>(beeper, flasher));. I also happen to think that forcing the client to use std::move at the call sites is good rather than bad, because it communicates the intended effect to the reader. Passing unique_ptr by value is the correct option here, it will accept temporaries just fine. And in my opionion, if you want safety quarantees like that, use Rust. I was a fan of the new C++ standards a while ago, but after having used them for some time, I found C is a lot nicer language. There's just way too much mental overhead when trying to write "idiomatic C++" and the compiler errors you sometimes get are just a waste of developer time.
好的表达方式应该让读者不必在脑内做翻译就能看懂，越贴近直觉越好。
我真希望当初能用一种不那么令人困惑的方式，把移动语义和右值引用这套东西加到 C++ 上。这是很重要的补充，但每次看到这样的代码，我都得在脑子里做体操，而在 Rust 里它就是自然成立。
ohazi查看英文原文
I really wish they had found a less confusing way to bolt this move semantics / rvalue references stuff onto C++. It's an important addition, but I find myself having to do mental gymnastics every time I see code like this, whereas in Rust it just works.
注释会随人员流动而失效，所以要么让它紧贴代码并有人维护，要么用类型和工具替代它。
关于指针所有权的注释，最糟糕的情况出现在人员流动频繁的大团队里。最终没人再知道这些注释和真实代码是怎么对应的，因为那些不断更换的开发者从来不去更新它们，结果就是要花好几天排查指针相关的 bug。如果你幸运地在一个允许使用现代 C++ 的团队，那就能用上所有可用特性来避免这种局面。
pjmlp查看英文原文
The worse thing about comments about pointer ownership are the big teams with lots of programmer attrition. Eventually no one knows any longer how those comments map to the real code, because lots of those ever changing developers never update them. Which leads to days delving into pointer related bugs. If one is lucky to work in a shop that allows for modern C++, then it is great being able to use all the available features to avoid this type of situation.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选