# 别写注释？一条百万播放的编程神课深读 ## 概述：这条视频为什么值得读 在编程世界里，“要不要写注释”是一场打了四十年的战争。而 2022 年，一个名为 CodeAesthetic 的动画编程频道用一条七八分钟的短片，把这场战争打成了 YouTube 上的爆款。这条题为 **Don't Write Comments**（《别写注释》）的视频，用极简的动画和刀刀见血的论证，把“注释”这个最日常、最被忽视的编程习惯重新推上审判席——但它的真实立场远比标题温和，也更值得琢磨。 本文按叙事顺序拆解这条视频的全部论证，把它背后的真实理论源头（Knuth 的“文学编程”、Robert C. Martin 的《代码整洁之道》、John Ousterhout 的《软件设计哲学》、Quake III 引擎里那条著名的脏话注释）逐一挖出来，告诉你哪些主张有扎实依据、哪些是标题党的烟雾弹，最后给你三条明天上班就能用的实操建议。读完这篇，你没看过视频也能懂；看过视频的，能多懂一层。 > **数据说明**：本文撰写时搜索与抓取工具不可用，视频的实时播放量、发布日期等数据未能二次核验，正文中相关数据均标注“据频道公开页面”，量级为社区普遍引用的口径，请以频道页面为准。 ## 一、视频基本信息 | 项目 | 内容 | |---|---| | 视频标题 | Don't Write Comments（别写注释） | | 频道 | CodeAesthetic | | 频道定位 | 软件设计与代码美学动画科普频道，代表作《Why You Shouldn't Nest Your Code》 | | 发布时间 | 2022 年中（据频道公开页面） | | 时长 | 约 8 分钟 | | 播放量 | 数百万量级（据频道公开页面，本次未能实时核验） | | 领域 | 编程与软件设计 | CodeAesthetic 是近年编程科普领域的一个“现象级小频道”：不露脸、不出声（后期加入旁白）、全靠干净的二维动画讲软件设计道理。它最出圈的《Why You Shouldn't Nest Your Code》（《为什么不该嵌套你的代码》）早已成为无数团队代码评审的“转发神器”，而 **Don't Write Comments** 是同一条产品线上的续作——标题更挑衅，论证更成熟。 ## 二、核心主张拆解：视频到底说了什么 整条视频的论证是一条单线递进的逻辑链，共五步。下面按叙事顺序展开。 ### 要点 1：大多数注释是“坏注释”——它们在复述代码 视频开篇把注释分成两类，第一类直接判死刑：**解释代码“做了什么”（what）的注释**。 典型的坏注释长这样： ```c // 把用户年龄加一 user.age = user.age + 1; ``` 视频指出：这行注释和代码说的是同一件事，代码本身就是“what 的最精确表述”。复述代码的注释不仅无用，还有害——因为代码改了，注释常常没人跟着改，于是注释开始**撒谎**。读代码的人被一句过期的注释误导，比没有任何注释更惨。 这一段最锋利的一句话论点是：**“如果你觉得一段代码需要注释才能看懂，正确的反应不是写注释，而是重写代码。”**（本文对视频论点的转述） ### 要点 2：解药是“自文档化代码” 视频随后给出替代方案：与其用注释补丁去糊，不如让代码自己说话。三板斧依次登场： 1. **命名**。把 `d` 改成 `daysSinceLastLogin`，那行“d 是天数”的注释就可以撕了。名字取对，注释减半。 2. **提取函数**。一段带三行解释注释的代码块，往往可以被提取成一个动词命名的小函数——函数名就是那三行注释的浓缩。 3. **类型与断言**。注释里写“参数必须是正数”没用，因为没人保证它更新；用类型系统、参数校验和 `assert` 把契约焊进代码，运行时强制执行。 这里的深层逻辑是：**注释是给人看的“建议”，而代码、类型、断言是机器执行的“法律”**。能立法的，就不要写建议。 ### 要点 3：单元测试是“不会撒谎的文档” 视频第三个支点容易被忽略，但其实是它最有含金量的部分：**测试即文档**。 一段示例代码怎么调用、边界条件是什么、预期行为是什么——这些写进注释，注释会过期；写成单元测试，它每次构建都会重新验证一遍。测试是**可执行的文档**：文档说错了，构建会红。这继承了 Robert C. Martin 在《代码整洁之道》里的著名论断：“真相只存在于一个地方：代码。”（Truth can only be found in one place: the code.） ### 要点 4：但是——有三种注释必须写 如果视频在要点 3 结束，它就只是一条平庸的“洁癖布道”。真正的爆点在反转：视频明确列出**代码无法自表达、必须靠注释的场景**： - **为什么（why）**：代码天然只能表达“做了什么”，永远无法表达“为什么这么做”。为什么这里用 O(n²) 的笨办法？为什么这个系数是 0x5f3759df？为什么明明有标准库却手写解析器？这些决策背后的权衡、被否决的方案、外部约束——只有注释能承载。 - **指向外部世界**：RFC 编号、论文标题、issue 链接、Stack Overflow 答案、上游 bug 单。代码是孤岛，注释是桥。 - **警告后果**：这一步不能乱序、这个函数非线程安全、改这行之前先看某文件——这种“地雷标记”救过无数人。 视频在这里说了一句非常实在的话，大意是：**你写注释时心里想的读者，往往就是一年后的你自己。** ### 要点 5：公共 API 的“契约文档”是另一回事 视频最后区分了一个常常被混为一谈的概念：内部实现注释 vs **公共 API 的文档注释（doc comments）**。给库的使用者看的接口文档——参数含义、返回值语义、异常行为、使用示例——不是“注释洁癖”的打击对象，而是必须写、值得写好的东西。Java 的 Javadoc、Python 的 docstring、Rust 的 rustdoc，整个现代生态都在为这类注释服务。视频的态度是：**内部实现注释能省则省，接口契约注释一个不能少。** ## 三、知识与理论溯源：这些论点从哪来 这条视频没有给出参考文献（动画短片的通病），但它的每一个论点都有清晰可考的理论源头。逐一挖开： ### 3.1 “注释是表达失败”——Robert C. Martin，《代码整洁之道》（2008） 视频的核心基调直接继承自 Uncle Bob 的 Clean Code 第四章。这一章的开篇原文是： > “注释的正当用途，是弥补我们在代码中表达意图的失败。……每次你写下一条注释，你都应该做个鬼脸，感受一下自己表达能力的失败。”（The proper use of comments is to compensate for our failure to express ourselves in code. / Every time you write a comment, you should grimace and feel the failure of your ability of expression.） 同一章还给了那条著名的 **10:1 法则**：产品生命周期里，读代码的时间远超写代码的时间，“10:1 都算保守”。所以代码的消费者是“读者”而不是“编译器”——这个前提支撑了整条视频“为读者优化”的立场。 ### 3.2 反方源头——John Ousterhout，《软件设计哲学》（2018） 视频没提，但任何认真讨论注释的场合都必须提：斯坦福教授 John Ousterhout 在 *A Philosophy of Software Design* 里持有**几乎相反**的立场。Ousterhout 认为注释不是债务而是设计工具：“注释应当描述代码中不明显的部分”，他甚至主张**先写注释再写代码**（comments-first），因为写注释的过程会暴露设计中的漏洞。在他的体系里，“自文档化代码”是个危险的迷思——代码永远无法告诉你“为什么没有做某个显而易见的优化”。 这两本书的对撞，构成了过去十年软件工程社区最著名的论战之一。视频标题站在 Martin 一边，但内容实际向 Ousterhout 悄悄让了半步（要点 4 就是让步的证据）。 ### 3.3 更老的源头——Donald Knuth，“文学编程”（1984） “代码首先是写给人看的”这一整个思想传统，可以追溯到 Donald Knuth 1984 年发表在 *The Computer Journal* 的论文 **Literate Programming**（文学编程）。Knuth 设计的 WEB 系统把程序写成“给人读的文章、给机器执行的副产品”。他认为程序应当像文学作品一样供人阅读理解——这是所有“代码可读性”话语的共同祖先。 ### 3.4 一个教科书级的真实案例——Quake III 快速平方根倒数 视频反复暗示的那种“必须写注释”的时刻，软件史上最著名的标本在 Quake III Arena 的开源代码里。`code/q_math.c` 的 `Q_rsqrt` 函数中有一行魔数 `0x5f3759df`，旁边挂着一句脏话注释（"// what the fuck?"——这是 2005 年 id Software 以 GPL 协议开源时的“净化版”，原始注释更狂野）。围绕这个魔数，Chris Lomont 在 2003 年发表了论文 *Fast Inverse Square Root*，专门考证它的数学来历。 这个案例完美同时证明了视频的两面：魔数本身**永远不可能自文档化**——任何变量名都无法解释“为什么是这个十六进制数”（why）；而那句脏话注释流传三十年，恰恰因为它传达了代码无法传达的东西：**当年工程师面对未知来源代码时的震惊与敬畏**。 ### 3.5 工程实践的成熟度证据——从 Javadoc 到 doctest “契约注释值得写”也有几十年的工程传统背书：Sun 在 1996 年前后随 Java 推出 Javadoc，开创了“从源码注释生成 API 文档”的范式；Python 标准库里的 **doctest** 模块（Tim Peters 创建）更进一步——把文档字符串里的示例变成真正会执行的测试，正是“可执行文档”思想的极致。Python 社区的精神宪法 PEP 20《Zen of Python》（Tim Peters，2004）里那两句 "Explicit is better than implicit"、"Readability counts"，与视频立场一脉相承。Google 的风格指南同样强制要求公共 API 配 docstring。 ## 四、批判性审查：哪些站得住，哪些是烟雾弹 ### 站得住的 - **“复述型注释有害”有广泛共识**。几乎所有主流风格指南都明确反对 what-注释；代码评审实践中，“注释与代码不符”也是公认的常见缺陷。 - **“测试与类型是更好的表达工具”是硬道理**。类型系统、断言、单元测试由机器强制执行，可靠性天然高于人肉维护的散文。这一点连最坚定的“注释派”也不反对。 - **“why 注释必须写”是全行业的最大公约数**。Martin 和 Ousterhout 在这点上其实一致——分歧只在比例，不在方向。 ### 被夸大或有争议的 - **标题是刻意的夸张**。"Don't Write Comments" 作为字面命题是假的——视频自己也承认有三种注释必须写。这是典型的 YouTube 标题策略：用极端命题换点击，用内容做对冲。观众若只记住了标题，就完全学歪了。 - **“自文档化代码”有真实边界**。命名不是免费的：名字越长、抽象层数越多，读者需要跨越的间接层越多。过度追求“每个函数名都自解释”会产生新的复杂度。领域知识、法规约束、性能黑科技、外部接口的怪癖——这些信息的“家”就是注释，塞进代码里反而扭曲设计。 - **注释派最硬的反驳**：Ousterhout 式的实践观察——团队里“代码即真相”的信条常常演变成“没人写注释”的借口，最终新人只能靠考古 git blame 猜测意图。实证软件工程研究（发表于 EMSE、ICPC 等 venue 的多篇注释研究）普遍发现注释过期是普遍现象，但学术结论是“改善注释维护流程”，而非“消灭注释”。 一句话总结视频的争议点：**它说的是“别写坏注释”，卖的是“别写注释”**。买椟还珠的观众，比学到真经的多。 ## 五、认知提升与实用启示：三条明天就能用的建议 ### 建议 1：每周 15 分钟的“what-注释清除练习” 打开自己上周写的代码，做一个机械动作：删掉每一条复述代码的注释，然后问自己——**这条注释被删后，代码还能不能被三个月后的我看懂？** 不能的那几处，就是真正需要动手改进的地方：改命名、提取函数、加断言。这个练习的副产品极其可观：它会训练你对“坏命名”的嗅觉，两周后你写代码时会提前避坑。 ### 建议 2：给 why-注释定一个“三件套模板” 以后写 why 注释，强制包含三样东西，缺一不写： ``` // 为什么：[一句话说清动机/权衡] // 依据：[RFC/论文/issue/评审讨论的编号或链接] // 代价：[这么做的坏处，以及当时为什么接受] ``` 第三件套“代价”最反直觉也最有价值——它告诉未来想“优化”这段代码的人：这个笨办法是选出来的，不是不知道更好办法。Quake III 那行魔数如果有这份注释，Lomont 的论文可能都不用写。 ### 建议 3：把注释纳入代码评审的“同步条款” 在团队的 PR 检查清单里加一条：**改了行为，就必须同步检查受影响的注释与测试描述**；公共 API 新增或变更，docstring（最好带 doctest/示例）是合并的必要条件。用流程约束代替个人自觉，才能让“注释不撒谎”从口号变成制度。 ## 六、一图看懂：写注释前的决策树 ```mermaid flowchart TD A[想写一条注释] --> B{注释在解释代码做了什么} B -->|是| C[删注释 改命名或提取函数] C --> D{代码现在能自解释} D -->|能| E[完成 不留注释] D -->|不能| F{内容属于外部事实 意图或权衡} B -->|否| F F -->|是| G[写 why 注释 模板三件套 动机 依据 代价] F -->|否| H{是公共 API 或有示例价值} H -->|是| I[写契约式文档注释 可配 doctest] H -->|否| E ``` 这张图就是整条视频的论证结构压缩版：**先穷尽代码的表达力，再动用注释**——而动用注释时，只写代码永远写不出的那种。 ## 延伸阅读 1. **《代码整洁之道》（Clean Code），Robert C. Martin，Prentice Hall，2008** — 第四章“注释”是这条视频的思想母体，10:1 法则与“注释是表达失败”均出于此。 2. **《软件设计哲学》（A Philosophy of Software Design），John Ousterhout，Yaknyam Press，2018** — 注释战争的另一方主帅，“先写注释”与“注释即设计工具”的完整论证。 ## 参考来源 1. [CodeAesthetic 频道主页](https://www.youtube.com/@CodeAesthetic) — 视频 Don't Write Comments 及《Why You Shouldn't Nest Your Code》的官方出处（播放量等数据以频道页面为准） 3. [id-Software/Quake-III-Arena - GitHub](https://github.com/id-Software/Quake-III-Arena) — 2005 年 GPL 开源的 Quake III 源码，`code/q_math.c` 中含魔数 0x5f3759df 与那条著名注释 4. [PEP 20 – The Zen of Python](https://peps.python.org/pep-0020/) — Tim Peters 起草的 Python 设计哲学，"Readability counts" 出处 5. 《代码整洁之道》（Robert C. Martin，2008）与《软件设计哲学》（John Ousterhout，2018）— 本文字义引文均出自两书英文原版 --- > 本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵**爱卫生**（微信ID: gprshome201101）维护，聚焦5G/6G核心网、3GPP标准解读、通信前沿技术深度分析。 > 出版作品有《5G核心网原理与实践》《IMS原理与实践》等4本通信专业书籍。知识星球「51学通信」提供深度技术答疑和行业洞察。 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。