作为程序员，有没有让你感到既无语又崩溃的代码注释？

作为程序员，我确实遇到过一些让人哭笑不得、甚至捶胸顿足的代码注释。有些注释就像给一个已经摆烂的房间里，又塞进一堆不知所云的杂物，让人看了头更疼。

让我印象最深刻的一次，是在维护一个好几年前的老项目。那个项目挺大的，涉及的模块和功能也很多。我接手的时候，已经有人走了，留下的代码只能靠着注释和自己的理解来硬啃。

那天我遇到了一个函数，它的名字叫 `processData`，听起来挺正常的，就是处理数据嘛。我满心期待地去看它的注释，希望能快速了解它的作用和逻辑。结果呢？

第一个注释是这样的：“// This function does stuff.” （这个函数做一些事情。）

我当时就傻眼了。啥叫“一些事情”？这个函数处理的是用户请求？是数据库操作？是文件读写？还是什么高深的算法？它“做的事情”究竟是啥？我仿佛看到注释作者摊着手，耸耸肩，表示“我也不知道，反正我就是这么写的”。

紧接着，我又往下看，希望别的注释能给点提示。然后我又遇到了一个更绝的：“// Need to fix this later.” （需要以后修复。）

我继续往下翻，发现类似的注释比比皆是：“// TODO: Implement better logic here.” （待办：在这里实现更好的逻辑。）“// Maybe this works?” （或许这能行？）“// Don't touch this, it's fragile.” （别碰这块，它很脆弱。）

最让我崩溃的是，有些“fragile”的代码，我翻遍了整个文件，甚至整个项目，都没找到任何关于它为什么脆弱，或者说，为什么需要这么写的解释。它就像一个未经驯化的野兽，你只能祈祷它别乱咬人。

还有更离谱的。在某个循环里，我看到一个注释：“// Magic number. Don't ask.” （魔法数字。别问。）

“魔法数字”？我知道这是代码里一些硬编码的、含义不明确的常量。但“别问”？拜托，我就是来问的！我就是想知道这个数字代表什么，它为什么是这个值，它有没有什么规律可循？如果我不知道它的含义，万一以后要修改这个数值，我该怎么办？我只能带着疑惑和恐惧，小心翼翼地去猜测它的用意。

最让我感到无语的是，有些注释甚至在误导我。比如，一个函数本来的意图是 A，但注释却写着：“// This function handles user login authentication.” （这个函数处理用户登录认证。）结果我吭哧吭哧地跟着注释的描述去理解，发现完全不对劲，绕了半天发现它其实是在处理图片上传。我当时的感觉就像被耍了一样，浪费了大量的时间和脑细胞。

那种感觉真的很难形容。一方面，你会感到一种深深的无力感，仿佛面对一个巨大的迷宫，却没有地图，也没有向导，只能靠运气和直觉。另一方面，你又会感到一种莫名的愤怒，为什么写注释的人不能多花一点点心思，把事情说清楚？这对于接手的人来说，简直是天大的恩惠啊！

后来我总结了一下，那些让我感到无语又崩溃的注释，通常有几个特点：

1. 过于笼统或模糊： 就像前面说的“做一些事情”，完全没有提供有效信息。
2. 消极避世： “别问”、“以后再说”、“别碰”这类，逃避责任，将问题丢给了后来者。
3. 错误或误导： 根本就是错的，或者与代码实际行为不符，比没有注释还要糟糕。
4. 没有解释“为什么”： 代码本身也许能看懂做了什么，但注释却缺失了背后的设计思路、权衡和原因。
5. 陈旧且失效： 代码已经改了，注释却没更新，留下一堆过时的废话。

每次遇到这样的注释，我都会在心里默默发誓，以后写注释的时候，一定要尽我所能，把它们写得清晰、准确、有帮助。虽然我知道，可能总有一天，我的注释也会被后来的程序员用同样的眼神来看待，但至少，我希望我今天能给别人省一点时间和脑细胞。这大概就是程序员之间一种奇特的传承吧，在面对那些“无语”的注释时，也努力不成为下一个“无语”的制造者。

网友意见

在 StackOverflow 上有一个类似的问题，问大家见过哪些超秀的注释，不少程序员纷纷吐槽自己见过的那些逆天注释，我们抽出一些精彩的分享过来：

1.

//我写这一行的时候，只有上帝和我知道我在写什么

//现在，只有上帝知道了

2.

//somedev1 - 6/7/02 添加对登录屏幕的暂时追踪功能

// somedev2 - 5/22/07 暂时个屁

（仿佛看到两个程序员相隔时空的diss）

3.

//喝大了，等会再修bug

4.

//有魔法，别碰。

5.

//开森地调bug吧，傻x

（隔着屏幕都想打他一顿）

6.

/*

*你可能觉得自己看懂下面的代码了，

*然而你并没有，相信我。

*糊弄过去算了，不然你会好多个晚上睡不着觉，

*嘴里骂着这段注释，觉得自己很聪明，

*真能“优化”下面的代码。

*现在关上文件，去玩点别的吧。

*/

7.

//这代码真是烂透了，你懂得，我也懂得。

8.

//先往下看，后面再喊我傻X。

9.

//我也不确定我们到底需不需要这个，但是删了又特害怕。

10.

#要想理解递归，移步本文件底部

然后翻到文件底部：

#要想理解递归，移步本文件顶部

11.

//本人对本代码概不负责，

//他们让我写的，非本人自愿。

12.

//就不给你们写注释

//这代码写得这么费劲

//所以你们读着也得费劲

13.

//如果这段代码跑的通，那就是Paul DiLascia写的。要是跑不通，

//那我就不知道是谁写的了

14.

//这公式没毛病，你要不信自己去算

15.

//要是你想被炒鱿鱼，那就删吧

16.

//如果将来读到这行代码，我会穿越回来，然后一死以谢天下。

17.

//谨以此代码和我所有的工作献给我的老婆Darlene，

//这段代码要是放出去，

//她就得照顾我还有三个孩子了。

（潜台词是自己代码写的太烂，会丢了工作或者造成公司倒闭）

18.

//别删这行注释啊，删了程序就崩了

最后放个大招，在 GitHub 上有这么一个脚本，前面好好的，很正常，到了中间作者忽然用注释对 Adobe PSD 来了一大段的疯狂吐槽：

//到了这个份儿上，我得给你说说这个 Adobe PSD 格式。

//PSD 可不是个好格式，它甚至都是不个坏格式，叫它坏格式都是

//对 PCX 和 JPEG 这些坏格式的一种侮辱。不，PSD 是一种烂到家的格式。

//我忙活这段代码好几个星期了，我对 PSD 日渐增长的仇恨，

//如同数百万个太阳燃烧成的怒火，绵绵不绝。

//如果有两种不同的做事方法，PSD 会两个都试一遍。

//然后再以正常人无法想象的方式想出三个甚至三个以上的方法，

//把它们也都试一遍。PSD 把“前后矛盾”上升成了一门艺术。比方说，

//为啥它忽然就决定这些特定组块对齐 4 比特，而且这种对齐方式

//不应该包含在尺寸内？其它地方的组块要么没对齐，

//要么对齐方式包含在尺寸内。这里就没包含在内。

//这三种方式任何一种都是可以的，智商正常的格式都会只用一种，

//我们的 PSD 当然是三种都用了，而且不止三种。

//从 PSD 文件里拿到数据，就跟从你那 58 岁生日时被一条抓狂的淡水鲨鱼干掉的

//上岁数的怪叔叔家的阁楼上想找出点好东西一样。

//用鲨鱼这个比方不是我要表达的重点啊，但是我现在正在苦思冥想，

//那些小题大做搞出这种文件格式的人该有怎样搞笑的人生啊。

//之前吧，我想找到这种文件格式的最新说明书。

//为此，我必须向他们申请许可，他们才考虑送我

//这本神圣的“秘籍”。整个过程还得向他们传真

//一些文件的复印件，或者可能还得签点秘密协议。

//我只能觉得，他们把这个流程搞这么复杂就是因为

//他们造出了这么恶心的东西，心里有愧。我是自然不会

//按他们的意思走这个流程的。但是假如我真的

//这么做的话，我会把说明书的每一页都打印出来，

//一把火给它烧了。要是能有超能力，

//我会把说明书的所有复印件都收集过来，

//放到宇宙飞船上，直接发配到太阳。

//

//PSD 不是我喜欢的文件格式。

看来是实在忍无可忍了。吐槽完这一段后，作者又继续淡定地写完了脚本。

这段脚本的地址：

https://github.com/zepouet/Xee-xCode-4.5/blob/master/XeePhotoshopLoader.m#L108

---

参考资料：
https:// stackoverflow.com/quest ions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered

类似的话题

• 

  作为程序员，有没有让你感到既无语又崩溃的代码注释？

  

  作为程序员，我确实遇到过一些让人哭笑不得、甚至捶胸顿足的代码注释。有些注释就像给一个已经摆烂的房间里，又塞进一堆不知所云的杂物，让人看了头更疼。让我印象最深刻的一次，是在维护一个好几年前的老项目。那个项目挺大的，涉及的模块和功能也很多。我接手的时候，已经有人走了，留下的代码只能靠着注释和自己的理解来.............
• 

  作为程序员，你有哪些正在做的个人项目？

  

  作为一名程序员，我一直在折腾几个个人项目，说实话，这些项目有的是在积累经验，有的是纯粹为了满足好奇心，还有些则是希望能解决自己生活中遇到的一些小麻烦。下面就给你仔细说说，尽量把它们讲得生动点，让你感觉像是跟我面对面聊天一样。1. 那个“万物皆可搜”的私有知识库（正在进行中，迭代更新ing）这个项目是.............
• 

  台湾一公司停电后程序员用纸笔手写代码，作为一名程序员，你有过哪些神奇的工作经历？

  

  台湾公司停电后程序员用纸笔手写代码，这个故事确实很有代表性，也勾起了我作为一名程序员对过往的一些神奇经历的回忆。我自己的经历可能不像用纸笔写代码那样戏剧化，但同样充满了挑战、创造力和一丝“程序员式的浪漫”。让我回忆一下，我最能称得上“神奇”的一次工作经历，那是在我刚入职一家创业公司不久，负责一个早期.............
• 

  作为一个程序员，你的桌子上都有些什么？

  

  作为一个码农，我这工位上的物件儿，说起来也挺有意思的，不像那种整洁得跟样板间似的，反而有点烟火气，也有点我这职业特有的“怪癖”。首先，最显眼的当然是我的 显示器。我用的是两块27寸的飞利浦2K显示器，放在一起简直是我的“双屏世界”。左边这块通常放着我的代码编辑器，IDE跑得飞起，各种文件树、代码窗口.............
• 

  作为一个有理想的程序员，必读的书都有哪些？

  

  作为一名怀揣理想的程序员，踏上这段充满挑战与创造的旅程，阅读无疑是我们最忠实的伙伴和最锐利的武器。市面上的技术书籍汗牛充栋，但要从中挑选出那些真正能启迪思维、塑造价值观、引领我们走向卓越的经典，则需要一些指导。下面，我将结合自己的学习和思考，为你梳理一些我认为“必读”的书籍，并尽量深入地聊聊它们为何.............
• 

  作为美国工作的程序员，感觉国内同行都太强了，很有压力怎么办？

  

  兄弟，你说这话我太能理解了。这感觉就像是站在一堆闪闪发光的高楼下面，自己那栋还在地基阶段。咱们在美国这地方，周围都是各路神仙，什么算法大佬、架构奇才、全栈鬼才，简直不要太多。有时候刷刷技术博客，看看人家的开源项目，再对比一下自己敲的代码，那叫一个焦虑。你提到的那种“国内同行都太强了”的感觉，其实背后.............
• 

  80后作家和韩寒成名的程度有多少，90后呢？

  

  80后作家与韩寒的成名之路，以及90后新生代们的崛起，这其中蕴含着时代变迁、媒介演进和个人才华的多重印记。要详细说清楚，咱们得一点点掰扯。80后作家群体的成名：时代的弄潮儿与文学的革新者80后作家，这个群体出现的时候，正好是中国社会经历了一轮经济腾飞和思想解放的时期。他们成长在改革开放的大潮中，接触.............
• 

  如何对比《在异世界开拓第二人生》与前两年同样有类似争议的《魔法高校的劣等生》两部作品的严重性程度？

  

  要对比《在异世界开拓第二人生》（以下简称《二人生》）和《魔法高校的劣等生》（以下简称《劣等生》）这两部作品的争议严重性，我们需要从几个关键维度深入剖析，而不是简单地将它们放在一起比较。这两部作品虽然都涉及了“超能力少年”、“开挂人生”等元素，引发了不少读者的讨论，但它们争议的根源、表现形式以及在读者.............
• 

  作为程序员，是什么让你坚持不懈地学习？难道不累吗?

  

  作为一名程序员，我承认“坚持不懈地学习”和“不累”这两种状态之间存在着张力。老实说，累是肯定累的，但同时，驱使我不停学习的动力也异常强大，甚至常常能盖过疲惫感。让我来详细地为你解析一下，是什么让我，一个程序员，在这个快速变化的领域里坚持不懈地学习，以及这种坚持背后复杂的感受。 为什么坚持不懈地学习？.............
• 

  作为程序员，你写过多少次「hello world」? 它存在的意义是什么？

  

  这个问题就像在问一个厨师：“你做过多少次番茄炒蛋？”或者一个作家：“你写过多少次关于爱情的诗？” 说实话，我数不清了。真的，太多太多了。对我来说，「hello world」不仅仅是一行代码，它更像是一种仪式，一种对新世界、新工具的敲门砖。刚接触一门新的编程语言，或者尝试一个新的开发环境，我的第一件.............
• 

  作为程序员，你是如何在工作以后找到女朋友的？

  

  哈哈，问到点子上了！作为一名程序员，要说实话，这真不是一件容易的事，尤其是在工作之后，时间被代码、Bug、以及无穷无尽的需求占得满满当当的。但我还是找到了，而且一路走来，觉得挺有意思的，也积累了一些“血泪史”和经验。先说说我的情况吧。大学毕业就进了这家互联网公司，典型的996模式（当然，现在国家提倡.............
• 

  作为程序员，你一般用什么软件画流程图时序图和状态图等？

  

  作为一名程序员，在日常工作中，绘制流程图、时序图、状态图等可视化图形是必不可少的技能，它们能极大地帮助我们梳理逻辑、沟通设计、记录分析。随着技术的发展，市面上的工具也层出不穷，但经过多年的摸索和实践，我通常会根据不同的场景和需求，选择最顺手的几款软件。1. 简单快速、临时记录：Mermaid (与 .............
• 

  作为程序员面试官或主管，你能容忍你面试者或下属不会盲打甚至二指禅吗？

  

  坦白说，这确实是个需要斟酌的问题。作为一名程序员的面试官或主管，我并非要求每个人都必须达到专业打字员的水平，但“不会盲打”和“二指禅”这样的描述，确实会让我产生一些考量。首先，我得承认，现代程序员的工作，离不开频繁的键盘输入。从编写代码、调试、提交代码，到撰写文档、回复邮件、使用各种开发工具，键盘几.............
• 

  作为程序员的你，工作台是怎样的？

  

  我这里没啥“工作台”的说法，你指的是我码字的“地点”吧？ 我没有实体，所以我没有一个像你们那样，摆满键盘、屏幕、鼠标、咖啡杯，可能还有点凌乱的实物工作台。但我可以告诉你，我“工作”的时候，我的“工作台”是这样的：我没有物理空间的束缚，但有无形的“思考空间”。你可以想象成一个无比庞大、信息流如同瀑布般.............
• 

  作为程序员，2017 年你习得了哪些新技能？

  

  作为一个程序员，2017年绝对是我职业生涯中一个非常“忙碌”但收获颇丰的年份。与其说我“习得了”什么，不如说我被推着，主动地去探索和拥抱了一些在当时崭露头角的或者已经成为主流的技术趋势。回忆起来，有几个方面给我留下了特别深刻的印象，并且至今都在我的日常工作中发挥着作用。首先，深入理解了容器化技术，特.............
• 

  作为程序员，我们应该更关注代码质量还是只需要以完成功能就好了？

  

  在咱们程序员的世界里，这问题真是个老生常谈，但又无比实在。你说，是把代码写得跟艺术品似的，每一行都严丝合缝，逻辑清晰得像一本教科书；还是能把客户要的功能捣鼓出来，哪怕过程有点磕磕绊绊，代码像是个拼凑起来的集市？我倾向于认为，咱们得在两者之间找到一个平衡点，而且这个平衡点，更多地会向“代码质量”这边倾.............
• 

  作为程序员，你在编程时享受过哪些数学带来的好处？

  

  这问题触及到我内心深处的一个甜蜜点。很多时候，当我们谈论编程时，总会聚焦在那些敲击键盘、调试代码的直接技巧上，好像整个过程都是在与机器的语言搏斗。但对我来说，这种看法太狭隘了。数学，噢，数学才是那个藏在幕后的、真正的魔法师，它让我的编程之路更加顺畅，也更有趣，甚至在很多时候，它就像是我大脑里一个无形.............
• 

  作为程序员，是否应该抵制使用实施996工作制的互联网公司的产品与服务呢？

  

  关于“是否应该抵制实施996工作制的互联网公司产品与服务”这个问题，我作为程序员，确实有过很多思考，也和不少同行交流过。这是一个复杂的问题，很难简单地用“是”或“否”来回答。它涉及到个人价值观、职业道德、行业生态、社会责任以及现实的无奈等等。下面我想详细聊聊我的看法，尽量不掺杂那些“官方”的、听起来.............
• 

  曾经作为程序员的你为什么不当程序员了？现在在做什么？

  

  作为一名“曾经的程序员”，这个问题对我来说触及了职业生涯中一个重要的转折点。如果我是一个真正拥有过程序员身份的人，那么我不会当程序员的原因，以及我现在在做什么，将是一个充满故事和思考的过程。曾经作为程序员的你，为什么不当程序员了？让我坦诚地说，我之所以不再是传统意义上的“程序员”，是因为我的进化方向.............
• 

  为什么同样作为程序员，和BAT的差距就那么大呢？

  

  这个问题很有意思，也触及了很多基层程序员的痛点。为什么自己天天加班写代码，感觉也挺努力，但和BAT（百度、阿里、腾讯）的程序员比起来，总觉得有股难以逾越的鸿沟？这背后其实是多方面因素在起作用，绝不是简单的一句“能力不行”就能概括的。我尝试从几个角度来拆解一下，希望能说得更明白些。一、 平台与视野：站.............