[读书笔记] 代码整洁之道（二）

继续整理本书的笔记。

第四章 注释

天真的年代里，我们认为代码里的注释就犹如公式旁边的备注，必不可少，越多与好，越详细越有用，常常技术头头们会把代码要有详细注释放在编码规范的头几条，甚至会有规定所谓的代码注释比，即多少行代码要配上多少行注释，每次代码复查时，“注释不够啊” “注释不清晰啊”头头A语重心长的对初级码农说道。现实的年代里，真的是这样的吗？一小组的人加班加点，不是在改bug，也不是在加新feature，而是在修补注释，每个类是做什么的，函数是打哪路酱油的，哪些是来参，哪些是出参，返回值又姓谁名啥。。。不一而举。年幼的我们还会沾沾自喜，“哈哈，多棒的代码，因为，满满的都是注释感啊。“ 直到代码过了几个迭代之后，我们发现：”WTF！这是谁写的注释，函数名字都对不上。“ 然后默默走开，边想，老子的注释可不会这样，边默默的复制粘贴，熟练的给新加的代码写注释。以前我总以为，代码的注释越多越好，越详细越好，看过本章之后才发现，越详细的注释只是掩耳盗铃而已。本章给出了两句简单却发人深省的总结：

注释不能美化糟糕的代码。
代码才是最好的阐述方式，注释不是。

很好理解，晦涩混乱的代码，即便注释在美妙，也只是隔靴挠痒，改变不了糟糕代码的事实，相反，简洁易懂，清晰明了的代码，配上天时地利的命名，即便没有注释，也是瑕不掩瑜。
当然，凡事不可极端，注释在某些情况下是必不可少的，例如，版权信息这些无法通过代码展现出来的东西，几条关于好注释和坏注释的参考：

好注释：

• 法律信息，身为程序员，版权问题没得商量。
• 对意图的解释和阐释，特别是某些表面看来不寻常甚至看似错误的代码（不过写这种代码真的好吗？）。
• 警示作用的注释，例如此处代码至少有8个坑，入坑需谨慎。
• TODO注释，用以标记由于某种原因，现在没有实现需要在将来添加的东西，当然务必要确保这些TODO真的To do了，现状很可能是，几年后的代码里几年前的TODO注释还在角落里面安静的做着美男子。如果发现不会取Do了，那就把这条TODO注释放心删掉吧，不疼。
• 对外提供的公共接口，这个不多说，多看看各种库的说明文档就知道了。
  除了以上几点，剩下的都是坏注释了。

坏注释：

• 自问自答，喃喃自语，注释完全成了下笔如有神的傀儡，例如：”//如果获取失败，那么就重来。“重来what？有多少爱可以重来。。。。
• 多于的注释，例如（欢乐：)）：

//Guess what? There are two bugs in the following code.Bug bug1 = 0;Bug bugN = 1;

• 误导性的注释，这个不多说，误导人大家都会。
• 循规蹈矩是的注释，例如函数头部要写上固定格式的注释，不管函数有多么简单，我想说，注释都让你玩出花来了，你咋不上天呢。例如：

/****@param1: input ...  ****//****@param2: output...  ****//****@return: ....       ****/

• 日志式注释，起初看到一堆常常的代码变更日志，觉得格外好，所有变化清清楚楚，但是如果变更记录需要我们手动维护，我们适用代码控制系统（SVN， Git）还有意义吗？
• 废话连篇，甚至是错误的废话，例如，不仅全是废话，还有错误，连废话都说说，还能干啥，揍凯~~：

//dateDate m_date;//nameString m_name;//ageunsigned int m_age;//ageAddress m_address;

• 位置标记，例如新家的代码段前加上”//Actions///////////////////////////////////////“。
• 括号后面的注释，例如循环的结束括号，另一个elseif的开始位置，代码需要加上特定的注释标识才能清晰，只能说你括号中间的代码太长了，拆分函数吧，骚年。例如：

for(...){//begin of for.........    while(...)    {//begin of while    ...    ...    ...    ...    ...    }//end of while...............}//end of for

• 注释掉的代码，这个最烦人，这样的代码就像堆积在犄角旮旯的杂物，我们总在想，”或许某一天还能用上吧，暂时先注释掉，不删，哈哈“。这种情况应该想收拾房间一样，果断”断舍离“吧，没用的代码，坚决删掉。
• 信息过多，如果有这样一段注释：

/* "Long, Long Ago" is a song dealing with nostalgia, written in 1833 by English composer Thomas Haynes Bayly. Originally called "The Long Ago", its name was apparently changed by the editor Rufus Wilmot Griswold when it was first published, posthumously, in a Philadelphia magazine, along with a collection of other songs and poems by Bayly. The song was well received, and became one of the most popular songs in the United States in 1844.In 1939 the tune was given new words (revised slightly in 1941) and a bouncier tempo. It became the 1942 Glenn Miller hit "Don't Sit Under the Apple Tree (With Anyone Else but Me)".In 1950, Patti Page recorded a cover as an alternate flip side to her hit record, "Tennessee Waltz".*/Class LongLongAgo {...};

总之

注释只是为代码服务的东西，切忌喧宾夺主，切记。