本文翻译自”Comments Only What the Code Cannot Say“，来自于《程序员应该知道的97件事》一书中的某个章节。

我们知道理论与实践之间存在差异。在实践中，这个差异远大于其在理论中所描述的那样 – 一份对注释（comments）的观察数据也证实了这一点。理论上，通常的注释代码的想法听起来是值得的：它可以为读者提供更多的细节，可以解释发生了什么事情。有什么能比自我帮助更具可帮助性的呢？然而在实践中，注释却经常变成一个破坏因素。与其他书面形式一样，编写好的注释也是有技巧的。这个技巧的主要内容是知道何时不写注释。

如果代码书写得不合乎语法规范，那么编译器、解释器以及其他一些工具会提出异议。如果代码在某方面功能不正确，评审、静态分析、测试以及在产品环境下的日常使用会发现绝大多数Bug。然而对于注释呢？在《The Elements of Programming Style》一书中Kernighan和Plauger曾指出“如果注释是错误的，那么它带来的价值就是零（甚至是负值）”。可是就是这样的注释却经常以一种编码错误所不能的方式散布并存活于代码库中。它们会持续不断地分散你的注意力，提供误导信息，细微但却持续地影响着程序员的思维。

那些在技术上没错，但却没有给代码带来任何价值的注释怎么样呢？这类注释简直就是噪音。重复描述代码含义的注释没有为读者提供任何额外价值 – 先用代码表达，再用自然语言复述不能让其看起来更加真实。被注释掉的代码不是可执行代码，所以无论对读者还是对代码运行时它都无法起到任何有用的效果。它自身也会很快地变得陈旧。版本相关的注释以及被注释掉的代码试图解决有关代码版本和历史的问题。但这些问题已经被版本控制工具（更加有效地）解决了。

代码库中普遍存在的噪音类注释以及错误注释助长了程序员们忽略所有注释的行为，他们要么略过注释，要么采取积极措施将注释隐藏起来。程序员是足智多谋的，他们会绕过任何被认为可能会造成破坏的事物：将注释折叠起来；更换颜色样式，使得注释的颜色与背景色相同；编写脚本过滤掉注释。为了使代码库免遭程序员们滥用聪明才智所带来的破坏，降低因忽视真正有价值的注释所带来的风险，我们应该像看待代码那样看待注释。每条注释都应该为读者带来一些价值，否则这些注释就是无用的，应该被删除或重写。

那么，什么才是有价值的呢？注释应该表达那些代码没有表达以及无法表达的东西。如果一段注释被用于解释一些本应该由这段代码自己表达的东西，我们就应该将这段注释看成一个改变代码结构或编码惯例直至代码可以自我表达的信号。我们重命名那些糟糕的方法和类名，而不是去修补。我们选择将长函数中的一些代码段抽取出来形成一些小函数，这些小函数的名字可以表述原代码段的意图，而不是对这些代码段进行注释。尽可能的通过代码进行表达。你通过代码所能表达的和你想要表达的所有事情之间的差额将为注释提供了一个合理的候选使用场合。对那些代码无法表达的东西进行注释，而不要仅简单地注释那些代码没有表达的东西。

By Kevlin Henney

今天是我的宝贝儿闺女-果果的一周岁生日。老爸特在此发文以表祝贺和纪念。

“时间飞逝”虽然是句套话，但它却真实地反映出这一年来的情况。的确是太快了！去年（2010年）的5月3日上午10点多，果果在大家的热切期盼下呱呱坠地，而如今小家伙儿都已经可以独立行走了。果果这一年来的成长还算是顺利。小家伙一直是母乳喂养（今天也正式断掉母乳了），体格很是健壮，各方面身体指数也在同龄平均水平之上。一年来基本没有什么头疼脑热的病状发生。果果食欲也很好，无论是母乳、奶粉、米饭、面条，还是鸡蛋、水果、蔬菜和其他辅食，果果从不拒食，这点也颇有爸爸的风范^_^。虽为小女孩儿，但果果在淘气方面丝毫不输于同龄的小男孩儿，这应该是继承了我的基因（她妈妈小时候据说是特别安静的）^_^。淘气也让果果付出了代价，特别是近一两个月，果果刚会站立和行走，一不小心就会出现磕磕碰碰，身上多处都负了小伤，这让我们心疼不已。

以前总是听到长辈们唠叨：“养儿/女累”、“养儿/女有操不完的心”、“不养儿/女不知父母恩”等等。今体验后感到确是这么回事儿。自从儿/女出生的那刻起，我们至少就要投入金钱、时间和精力三种成本。金钱我就不说了，大家都懂的。对于正处于事业起步期的年轻父母来说，时间和精力成本更可观。每天带着疲惫的身体回家，本渴望能得到很好的休息，但小宝贝半夜里一声啼哭，就把你从好梦拽回到现实中-哄孩子、喂水、喂奶、把尿/换尿裤；周末，本可以会友、充电、读书、出行，但看到孩子眼神中对你的渴望，你只能进入到超级奶妈或奶爸的角色中去。很多家长，包括我都有这样的体会：周末/假期比上班还要累。另外我们俗称的“操心”，实际上是一种焦虑的表现，这种焦虑甚至会让你茶不思、饭不想、整晚失眠，而这一切也都来自于孩子。孩子身上所表现出的任何一点异常都会导致父母处理焦虑的状态，比如厌食、生病、不正常睡觉、身体发育水平与其他孩子相比有异样等等。
 
“累并快乐着”，这是大多数家长们，当然也包括我所达成的共识。我们付出的同时，我们也收获了也许是人间中最至纯的快乐-天伦之乐。宝宝们每一声清脆的笑声都能在我们心底泛起幸福的涟漪；每一次展现给我们的笑脸都仿佛初春那缕缕温暖的阳光映照在我们的心田。这些宝宝带给我们的快乐，让我们把疲惫抛到了九霄云外。这种快乐，需要你静下来细心体会。

感受就这么多了。我的养女之路才刚刚起步，任重道远啊。

最后，祝果果生日快乐，健康幸福！

附：果果今天逛宜家的部分照片：

今天我一岁了，妈妈带我逛宜家

宜家餐厅的美食真多，可惜我还不能吃

先记住地图以防迷路

宜家的床好软啊

妈妈，这个木马搬回家可以吗？

妈妈给我买的生日礼物，我好喜欢