在编程世界里，“要不要写注释”是一场打了四十年的战争。而 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 是同一条产品线上的续作——标题更挑衅，论证更成熟。
整条视频的论证是一条单线递进的逻辑链，共五步。下面按叙事顺序展开。
视频开篇把注释分成两类，第一类直接判死刑：解释代码“做了什么”（what）的注释。
典型的坏注释长这样：
// 把用户年龄加一
user.age = user.age + 1;
视频指出：这行注释和代码说的是同一件事，代码本身就是“what 的最精确表述”。复述代码的注释不仅无用，还有害——因为代码改了，注释常常没人跟着改，于是注释开始撒谎。读代码的人被一句过期的注释误导，比没有任何注释更惨。
这一段最锋利的一句话论点是：“如果你觉得一段代码需要注释才能看懂，正确的反应不是写注释，而是重写代码。”（本文对视频论点的转述）
视频随后给出替代方案：与其用注释补丁去糊，不如让代码自己说话。三板斧依次登场：
d 改成 daysSinceLastLogin，那行“d 是天数”的注释就可以撕了。名字取对，注释减半。assert 把契约焊进代码，运行时强制执行。这里的深层逻辑是：注释是给人看的“建议”，而代码、类型、断言是机器执行的“法律”。能立法的，就不要写建议。
视频第三个支点容易被忽略，但其实是它最有含金量的部分：测试即文档。
一段示例代码怎么调用、边界条件是什么、预期行为是什么——这些写进注释，注释会过期；写成单元测试，它每次构建都会重新验证一遍。测试是可执行的文档：文档说错了，构建会红。这继承了 Robert C. Martin 在《代码整洁之道》里的著名论断：“真相只存在于一个地方：代码。”（Truth can only be found in one place: the code.）
如果视频在要点 3 结束，它就只是一条平庸的“洁癖布道”。真正的爆点在反转：视频明确列出代码无法自表达、必须靠注释的场景：
视频在这里说了一句非常实在的话，大意是：你写注释时心里想的读者，往往就是一年后的你自己。
视频最后区分了一个常常被混为一谈的概念：内部实现注释 vs 公共 API 的文档注释（doc comments）。给库的使用者看的接口文档——参数含义、返回值语义、异常行为、使用示例——不是“注释洁癖”的打击对象，而是必须写、值得写好的东西。Java 的 Javadoc、Python 的 docstring、Rust 的 rustdoc，整个现代生态都在为这类注释服务。视频的态度是：内部实现注释能省则省，接口契约注释一个不能少。
这条视频没有给出参考文献（动画短片的通病），但它的每一个论点都有清晰可考的理论源头。逐一挖开：
视频的核心基调直接继承自 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 都算保守”。所以代码的消费者是“读者”而不是“编译器”——这个前提支撑了整条视频“为读者优化”的立场。
视频没提，但任何认真讨论注释的场合都必须提：斯坦福教授 John Ousterhout 在 A Philosophy of Software Design 里持有几乎相反的立场。Ousterhout 认为注释不是债务而是设计工具：“注释应当描述代码中不明显的部分”，他甚至主张先写注释再写代码（comments-first），因为写注释的过程会暴露设计中的漏洞。在他的体系里，“自文档化代码”是个危险的迷思——代码永远无法告诉你“为什么没有做某个显而易见的优化”。
这两本书的对撞，构成了过去十年软件工程社区最著名的论战之一。视频标题站在 Martin 一边，但内容实际向 Ousterhout 悄悄让了半步（要点 4 就是让步的证据）。
“代码首先是写给人看的”这一整个思想传统，可以追溯到 Donald Knuth 1984 年发表在 The Computer Journal 的论文 Literate Programming（文学编程）。Knuth 设计的 WEB 系统把程序写成“给人读的文章、给机器执行的副产品”。他认为程序应当像文学作品一样供人阅读理解——这是所有“代码可读性”话语的共同祖先。
视频反复暗示的那种“必须写注释”的时刻，软件史上最著名的标本在 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）；而那句脏话注释流传三十年，恰恰因为它传达了代码无法传达的东西：当年工程师面对未知来源代码时的震惊与敬畏。
“契约注释值得写”也有几十年的工程传统背书：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。
一句话总结视频的争议点：它说的是“别写坏注释”，卖的是“别写注释”。买椟还珠的观众，比学到真经的多。
打开自己上周写的代码，做一个机械动作：删掉每一条复述代码的注释，然后问自己——这条注释被删后，代码还能不能被三个月后的我看懂？ 不能的那几处，就是真正需要动手改进的地方：改命名、提取函数、加断言。这个练习的副产品极其可观：它会训练你对“坏命名”的嗅觉，两周后你写代码时会提前避坑。
以后写 why 注释，强制包含三样东西，缺一不写：
// 为什么：[一句话说清动机/权衡]
// 依据：[RFC/论文/issue/评审讨论的编号或链接]
// 代价：[这么做的坏处，以及当时为什么接受]
第三件套“代价”最反直觉也最有价值——它告诉未来想“优化”这段代码的人：这个笨办法是选出来的，不是不知道更好办法。Quake III 那行魔数如果有这份注释，Lomont 的论文可能都不用写。
在团队的 PR 检查清单里加一条：改了行为，就必须同步检查受影响的注释与测试描述；公共 API 新增或变更，docstring（最好带 doctest/示例）是合并的必要条件。用流程约束代替个人自觉，才能让“注释不撒谎”从口号变成制度。
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
这张图就是整条视频的论证结构压缩版：先穷尽代码的表达力，再动用注释——而动用注释时，只写代码永远写不出的那种。
code/q_math.c 中含魔数 0x5f3759df 与那条著名注释本文由「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 等场景全覆盖。