开发浅谈-代码注释

一：前言

       这是本人的第一篇博客，其实没有想好写一些什么技术方面的文章，后来想了想先总结一下5年来的开发经验以及踩过的坑，简单说一说自己对代码注释的理解吧！内容纯手打，欢迎大家指教！

二：亲身经历

       5年来亲身参与的项目也挺多了，包括原有项目二次开发及日常维护，也有新落地的项目。在这个过程中，自己也从一个小白逐渐的积累经验，一步一步的成长着。而说到注释，可能很多人都会有或多或少的感慨和心酸吧。

       先说原有项目二次开发的事吧，由于之前的项目开发过程中有好几批人都参与了，据说当时项目进度很赶，很多细节方面都没有过多的要求，而每个人开发的风格、命名方式等等方面都有不同，最后导致整个项目变得特别庞大。冗余代码、无注释的代码等情况随处可见。

       到了我接手进行二次开发的时候，看到这个源代码真的是。。。（想不出怎么形容当时的感受了，词穷了，实在是找不到任何一个词语能够形容那种感觉），简单说几个情况吧，大家脑补：

       1.代码中变量、方法名的命名很随意，例如下面这样：

int a = 10;
String hehe = "123456";

public static void heihei(){
    //处理逻辑部分
}

       2.大量代码没有注释或缺少注释的情况，例如下面这样：

public static List delTelData(List list){
	String x;
	String s;
	boolean flag = true;
	List listx = list;

	List<String> dateList = new ArrayList<String>();
	int month;
	int date;
	
	Calendar cal = Calendar.getInstance();
	cal.add(Calendar.DATE, -30);
	for(int i=0;i<30;i++){
	cal.add(Calendar.DATE, 1);
	month = cal.get(Calendar.MONTH)+1;
	date = cal.get(Calendar.DATE);
	dateList.add(cal.get(Calendar.YEAR)+""+(month>9?month:"0"+month)+(date>9?date:"0"+date));
	}
	for(int j=0;j<dateList.size();j++){
		flag = true;
		s = dateList.get(j);
		for(Object sx:list){
			x = (String)((Map)sx).get("X");
			if(s.equals(x)){
				flag = false;
				continue;
			}
		}
		if(flag){
			Map map = new HashMap();
			map.put("X", s);
			map.put("Y", new BigDecimal(0));
			map.put("S", "总成绩");
			listx.add(j, map);
		}
	}
	
	return listx;
	}

       3.大量冗余代码

              基本是同样的处理逻辑和需求，但是在很多代码中重复的出现，让人抓狂的很。搞得我这个也不敢动，那个也不敢动，         只能通过debug的方式一步一步的跟踪，然后找到对应的代码进行修改。（太难了~~~~~）

       当时看到这些的代码后，作者个人当时的感觉真的很无奈、头疼，感觉作为一个程序员来说，太灰暗了有木有。

三：注释的重要性

       以作者的个人经历来说，如果要我自己来给一段代码评分的话，我觉得干净、整洁的处理逻辑可以占到60分，而完善、明确的注释则占40分（最少值这个分值）。下面来说说我个人的见解。

       对于开发人员来说，我们面对的代码无非两种情况：别人的代码和我们自己的代码。先来说说别人的代码。当我们接受别人的代码时，首先就是要理清业务流程，在梳理整个业务流程的过程中，如果你看到的是一个个没有注释的代码块，那么恭喜你，你进坑了，如果业务流程简单还好说一些，如果这个业务流程复杂一些，那么梳理业务流程的工作对于你来说就是一团乱麻中找线头一样的处境。你需要将整个流程进行debug，然后一步一步的进行梳理。这将会极大的增加你的工作量，可能原本只需要半天时间就可以梳理通的流程，实际上你却需要3天，甚至更多的时间；那么，如果你看到的是有明确注释说明的代码，请记得感谢你的前辈，并发扬这种风格，这是一个合格开发人员必备的素养。

       下面来说一说另一种情况：我们自己的代码。开发过程中，最初的时候，我并没有那么注重注释的编写，有时间就写注释，如果时间赶不及，当时就想着先不写了，有时间再找回这里补上注释。但是，实际情况是，过了一段时间后你发现自己还是抽不出来时间或者即使抽出来时间了，但是找回到之前的代码部分，突然发现自己竟然也想不起当时的思路了，更不用说补全注释了。就因为这个原因，后来我没有漏掉写注释的步骤，因为我确信再过一段时间回来补注释的时候，我可能就记不得这里的处理逻辑了。

       所以，对于开发人员来说，注释真的非常重要。既可以以文字的方式保留当时的思路，而且最重要的是可以很大程度上减少后期二次开发和项目运维的成本。有清晰注释的代码可以让后期二次开发变得简洁很多，可以节省很多时间，让更多的时间用在代码开发和优化上，而不是通过debug梳理业务流程上。

四：养成良好的代码注释习惯

       书写注释是每个开发人员必须要具备的能力，我们要克服个人的惰性，不能得过且过，不说什么为公司节省成本，为项目减少工时消耗，只求做一个合格的开发人员，能让以后接你工作的人能衷心的感谢你的注释，能让他不会骂你是个坑货，我觉得这样就很好。

       当然注释也并不是说越多越好，这样就会搞得大篇幅都是注释，而代码却少的可怜，这就丢掉了注释的本意。书写注释的时候只要在必要的地方比如变量、类、方法、参数、重要的处理逻辑等必须要注释留存当时的思路，以便保留代码的可读性；而对于一些简单的处理，注释可以选择精简方式，简单注释一下逻辑思路即可。

五：总结

       文章的最后做一个简单的总结吧。首先，一定要克服自身的惰性，养成书写代码的好习惯，要知道代码和注释都是很重要的，书写注释的同时也是在记录自己的思路；其次，优雅的注释是一点一点靠经验积累得来的，写注释的同时也是在锻炼我们的语言表达能力，经过经验积累，可以提高我们书写注释的质量；最后，（拔高一下觉悟吧~~~~~）书写注释绝对能够体现开发人员个人素养，为了提升我们的个人素养，请培养自己养成良好的书写注释的习惯。

---

       以上为我对代码注释的个人见解，由于第一次写文章，文笔欠佳，大家见谅。欢迎各位高手指正，谢谢！