【代码注释】浅谈对于代码注释的理解

楔子：“这里的山路十八弯，这里的水路九连环”；智慧的古人就懂得，通过把山路修成九曲十八弯来战胜陡峭的高坡。看则舍近求远绕圈而行，实为拿路程换高度，为完成登顶而蓄势待发。这种螺旋上升亦进亦退的智举，在生活中也不胜枚举。

 

　　代码，源自一门门计算机程序设计语言，就是人类与计算机之间交流的桥梁。代码注释，顾名思义，就是对这些特别的语言更加符合人类自然常识的解释，换句话说就是用更加通俗的方式让别人甚至自己理解代码的含义。

　　Level 1:犹记当年初窥编程世界之时，一些基础入门级别的书籍在介绍到代码注释这一部分的时候，都会不约而同的强调“大家一定要学会写好注释”，大体上给人的初步印象就是，代码注释多多益善。

　　Level 2:有了一定编程基础之后呢，一般大家都会兴致勃勃的写上一两个练手级的小项目，在不断应用上新技术的同时，“多写注释”的四字箴言早已经被抛在脑后。而且呢，一般一个逻辑不太复杂的小项目经过自己耐心的调试之后，也能够最终华丽丽的问世。沉浸在小小的成就感的同时，不禁在脑中可能就形成了“注释这个东西有点鸡肋呀，你看我也没怎么用到注释，不也把这么nice的项目给整出来了嘛（傲娇脸）”。

　　Level 3:画风一变，开始接触一些企业级的大项目了。不管是从需求分析开始接手也好，还是半途拿到别人的项目也罢，惊人的代码量，复杂的系统逻辑，整个人都蒙了！！！此时可能无需旁人多言，自己也会想把大腿拍青，”代码注释真是太重要了！别说接手别人的项目时需要通过注释才能快速理解整个项目，就连自己亲手写的代码，一旦庞大起来，时间已久，不看注释也完全不知道从何下手了，详细的注释真是能做到事半功倍！“

　　Level 4:阅历越来越丰富的我们，开始不断听到这样的声音”代码注释产生的原因，究其根本是代码本身的可读性太差！“，先抛开不管这样的观点是出自业内泰斗还是初生牛犊之口，仔细琢磨一下这句话，确实有一定的道理。如果代码可读性很强，使人一目了然，那干嘛还要另外添加注释呢？这样一解读，其逆反命题也很有道理呢。（哈哈哈，这里就不卖关子了，其实很多编程大作之中，也都有提到这样的观点）

　　Level 5:深得注释要领的我们，开始把更多的精力投入到代码自身的可读性上面去，写出了漂亮的代码的同时，开始减少注释的量。然后出任CEO，迎娶白富美，走上人生巅峰。。。然后梦就醒了2333；两眼一睁，发现自己在项目经理的办公室里，他老人家也在同时发现了醒来的你，开始破口大骂：”你是第一天做项目吗？你这光秃秃的代码是在逗我吗？注释都没时间添？“当你据理力争，解释一通之后，经理可能长叹一口气，然后语重心长的对你说：”孩子，咱们是在中国呀！“众所周知，中国特色码农主义世界里，跳槽是一件多么频繁的事情（这里就不做深入讨论了）。你的项目不写上详实的注释，再加几个说明文档，负责人甚至会以为你想撂挑子不干了！

　　Level max:从“需要写注释”到“不需要写注释”，又从“注释多多益善”再到“代码越好注释越少”，最后还要考虑下本国国情（捂脸）Orz，就在这一进一退之中，我们对于注释的认识也在螺旋上升中。可能这个问题本身就不存在一个标准的答案（那我们还一直纠结这个问题干嘛！有病？），但是这样的矛盾，可能就是我们提高的桎梏，一个体现水准体现内力的地方。一般情况下，我们可以官方性的把“要不要写注释”这样的问题归结为：根据情况结合自己的经验而定~（(╯‵□′)╯︵┻━┻这种情况还是上点干货好了，比如这样一段代码：

public void fun() {
    ToolOne t1 = Tool.getInstance();
    t1.setAttr("xxx","yyy");
    t1.setUrl("zzz");
    t1.execute(Tool.DEFAULT);

    ToolTwo t2 = Tool.getInstance();
    t2.setAttr("xxx","yyy");
    t2.setUrl("zzz");
    t2.execute(Tool.DEFAULT);

    ToolThree t3 = Tool.getInstance();
    t3.setAttr("xxx","yyy");
    t3.setUrl("zzz");
    t3.execute(Tool.DEFAULT);
}

这样一段代码，不管是方法名还是内容，谁能知道这是在干嘛！那么我们是要加注释喽？比如这样：

/*
 *把大象装进冰箱里
 */
public void fun() {
     //第一步：把冰箱门打开
     ToolOne t1 = Tool.getInstance();
     t1.setAttr("xxx","yyy");
     t1.setUrl("zzz");
     t1.execute(Tool.DEFAULT);
 
     //第二步：把大象塞进去
     ToolTwo t2 = Tool.getInstance();
     t2.setAttr("xxx","yyy");
     t2.setUrl("zzz");
     t2.execute(Tool.DEFAULT);
 
     //第三步：把冰箱门关上
     ToolThree t3 = Tool.getInstance();
     t3.setAttr("xxx","yyy");
     t3.setUrl("zzz");
     t3.execute(Tool.DEFAULT);
}

这样是不是一目了然了呢~哈哈哈，那么我们来看一看高级点的办法，就是以代码来充当注释，看招：

public void take_elephant_into_icebox() {
     openIcebox();
     setElephantIn();
     closeIcebox();
}

public void openIcebox(){
     ToolOne t1 = Tool.getInstance();
     t1.setAttr("xxx","yyy");
     t1.setUrl("zzz");
     t1.execute(Tool.DEFAULT);
}

public void setElephantIn(){
     ToolTwo t2 = Tool.getInstance();
     t2.setAttr("xxx","yyy");
     t2.setUrl("zzz");
     t2.execute(Tool.DEFAULT);
}

public void closeIcebox(){
     ToolThree t3 = Tool.getInstance();
     t3.setAttr("xxx","yyy");
     t3.setUrl("zzz");
     t3.execute(Tool.DEFAULT);
}

如何，现在不管是从方法名take_elephant_into_icebox到方法体的三句代码，整个代码做到了不写一行代码也一目了然的效果，对于一般的阅读者来说，也能很清晰准确的理解这块代码的含义、运行逻辑和最后实现的功能。

　　所以嘛，身为一个并不资深的猿类，也已经意识到这个螺旋上升理解注释的模式，当然上面所分等级也仅限个人的一面浅见，level max并非绝对，仅为大家日后学习不断改进自己的认知水平而提供一个参考，总之也希望我们都能在这条遥不见终点的路上越走越远吧2333~To be continue......