B轮融资|代码注释的艺术，优秀代码真的不需要注释吗？芯片|创投圈

文章图片

前言前天回家路上，有辆车强行插到前面的空位，司机大哥吐槽“加塞最可恶了” ，我问“还有更可恶的吗” ，司机大哥淡定说道“不让自己加塞的” 。似乎和我们很类似，我们程序员届也有这2件相辅相成的事：最讨厌别人不写注释，更讨厌让自己写注释。一段糟糕的代码，往往大家最低的预期是把注释写清楚，最合理的做法通常应该对代码做优化。如果我们将代码真正做到了优秀，我们是否还需要注释？
注释的意义 ; **************************************************************************; * RAMinit Release 2.0 *; * Copyright (c) 1989-1994 by Yellow Rose Software Co. *; * Written by Mr. Leijun *; * Press HotKey to remove all TSR program after this program *; **************************************************************************; Removed Softwares by RI:; SPDOS v6.0F WPS v3.0F; Game Busters III IV; NETX ( Novell 3.11 ); PC-CACHE; Norton Cache; Microsoft SmartDrv; SideKick 1.56A; MOUSE Driver; Crazy (Monochrome simulate CGA program); RAMBIOS v2.0; 386MAX Version 6.01 注释是对代码的解释和说明，本质目的是为了增强程序的可读性与可解释性。注释会随着源代码，在进入预处理器或编译器处理后会被移除。这是雷布斯1994年写的一段MASM汇编代码，注释与代码整体结构都非常清晰。如果说代码是为了让机器读懂我们的指令，那注释完全就是为了让我们了解我们自己到底发出了哪些指令。
争议与分歧注释的起源非常早，我们甚至已经查阅不到注释的由来，但现在任何一种语言，甚至几乎任何一种文本格式都支持各式各样的注释形式。但如何使用注释，其实一直是一个备受争论的话题。当我们接手一段‘祖传代码’时，没有注释的感觉简直让人抓狂，我们总是希望别人能提供更多的注释。但软件届也有一段神话传说，叫做『我的代码像诗一样优雅』。有注释的代码都存在着一些瑕疵，认为足够完美的代码是不需要注释的。
坏代码的救命稻草 The proper use of comments is to compensate for our failure to express ourself in code. -- Robert C. Martin 《Clean Code》译：注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败
Clean Code 的作者Robert C. Martin可以说是注释的极力否定者了，他认为注释是一种失败，当我们无法找到不用注释就能表达自我的方法时，才会使用注释，任何一次注释的使用，我们都应该意识到是自己表达能力上的失败。PHV的系统架构师和负责人Peter Vogel ，同样也是一名坚定的注释否定着，他发表了一篇文章 why commenting code is still bad 来表述为代码添加注释在某种程度上可能是必要的，但确实没有价值。事实上，我们也确实经历着非常多无价值的注释，以及完全应由代码来承担解释工作的“职能错位”的注释。
零注释

糟糕的代码加上完全不存在的注释，我喜欢称呼它们为『我和上帝之间的秘密』，当然过2个月后也可以称之为『上帝一个人的秘密』。压垮程序员最后一根稻草的，往往都是零注释。可以没有文档，可以没有设计，但如果没有注释，我们每一次阅读都是灾难性的。当我们抱怨它一行注释都没有时，其实我们是在抱怨我们很难理解代码想要表达的含义，注释是直接原因，但根本原因是代码。零注释往往和坏代码一起生活， “没有注释”的吐槽，其实本质上直击的是那堆歪七扭八的英文字母，到底它们想表达什么！
无用注释
/** * returns the last day of the month * @return the last day of the month */public Date getLastDayOfMonth(Date date) { Calendar calendar = new GregorianCalendar(); calendar.setTime(date); calendar.set(Calendar.DAY_OF_MONTH calendar.getActualMaximum(Calendar.DAY_OF_MONTH)); return calendar.getTime(); 这是典型的废话注释，读代码时代码本身就能很好的表达具体的含义，我们完全不需要看注释，并且注释也不会给我们提供更多有效的信息。无用注释或许是零注释的另一个极端，我们担心自己写的代码被人所吐槽，于是尽可能去补全注释，当你为 getLastDayOfMonth() 补一段 get last day of month 的注释时，恭喜你，你得到了双倍的代码。