【优雅编程之道】之注释
开心一笑
【今天朋友当着我们的面甩一张卡给他媳妇，说随便刷，我们心想他何时变得这么man，只见他媳妇甩起卡就往他脸上扔，说：“有脾气给信用卡，给我什么公交卡”。我们在一旁笑爆了！神回复：他的意思应该是让媳妇有多远滚多远吧？】
提出问题
如何写出优雅的注释???
唯美图片
解决问题
优雅的注释
温习Java的三种类型注释
Java提供3中类型的注释，具体如下：
- 单行注释(single-line) ：短注释 //……
- 块注释(block) ：多行注释 /……/
- 文档注释(javadoc)：注释若干行，并写入javadoc文档 /*……/
程序清单 1-1
/**
* 我是文档注释，除了可以注释下面方法作用，
* 还可以用来自动生成文档
* @author 阿毅
* @date 2017/02/06
*/
@Test
public void test(){
//我是单行注释,用于短注释
System.out.println("单行注释");
/* 我是多行注释，如果注释内容太多，
一行放不下，就使用我 */
System.out.println("多行注释");
}
注释需要死记的3句名言
1.代码即注释，真正好的注释就是考虑不用写注释,注释就是一种失败。 ——《clean code》
2.错误的注释比不注释更可怕。
3.没用的注释生命力是很顽强的。如果不删掉，我想，将来你们的软件部署到月球上，它们还神一般的存在。 ——《编写高质量代码：改善Java程序的151个建议》
两种单行注释的困难抉择
我们先看下面的例子：
程序清单 2-1
/**
* 描述:比较注释的使用方法
* @author 阿毅
* @date 2017/02/06
*/
@Test
public void test(){
//第一种写法：注释放在代码上面
//打印ay
System.out.println("Ay");
//打印and
System.out.println("and");
//打印al
System.out.println("Al");
//第二种写法：注释放在代码后面
System.out.println("Ay");//打印ay
System.out.println("and");//打印and
System.out.println("Al");//打印al
//两种注释优劣的比较
Collections.EMPTY_LIST.stream().filter(entry -> entry.toString().equals("a")).count();//两种注释的比较
}
上面的注释都是废话注释，只是为了方便举例。从上面代码可以看出，如果某一行的代码特别长，把注释放在代码后面就显得很不合适了。所有个人的建议是：使用第一种写法。具体原因有3点：
- 先看注释再看代码比先看代码再看注释，能更快理解代码含义，节省时间。
- 第一种注释不用担心代码过长造成阅读不方便。
- 如果需要注释的内容比较多，第一种注释不用担心注释内容过多造成代码过长。
综上所述，我更建议使用第一种注释。
括号后的注释
在括号后面写注释，看起来不直观，而且代码可读性也不高，建议另起一行。具体如下：
程序清单 2-1
@Test
public void test(){
boolean flag = true;
if(flag){//错误注释:flag状态的转换
flag = false;
}else{
flag = true;
}
try{//错误注释
......
}catch (Exception e){//错误注释
}
//正确注释:flag状态的转换
if(flag){
flag = false;
}else{
flag = true;
}
}
无情删掉注释掉的代码
项目开发中，开发人员经常会把代码注释掉，接手人员又不知道该注释的代码是否还有用。于是被注释的代码就像幽灵一样，紧紧的缠着项目。它们的生命力无比强大，估计有一天你们的项目卖到月球上去，注释代码还存在。如果它真的有用，就不会被注释掉，无情的删掉它吧！抱着不是你死，就是它亡的决心。
程序清单 2-1
@Test
public void test(){
//String s = "该变量没有用处";
//List<String> list = new ArrayList<>();
System.out.println("上面的变量s和集合list没有任何用处，无情删除吧");
System.out.println("结束");
}
TODO注释的妙用
开发过程中，时常因为工期赶而没有时间写好代码。每个开发人员都有意识，这个功能以后要重构或优化，但往往之后就不了了之了。一个有用的注释就是TODO注释，具体如下：
程序清单 2-1
@Test
public void test(){
List<String> userIds = new ArrayList<>();
for(int i=0;i<userIds.size();i++){
//废话注释：通过id查找用户（只是为了说明方便）
User user = userService.findById(userIds.get(i));
//TODO 由于工期短，在for循环中查询数据库数据，后期必须优化
}
}
单行注释和多行注释不要混用
虽然多行注释可以嵌套单行注释，但是我们不建议你这样混合用，具体实例如下：
程序清单 2-1
@Test
public void test(){
/*这里是多行注释，可以嵌套单行注释
//这里是单行注释
*/
System.out.println("多行注释可以嵌套单行注释");
/*这里是多行注释
/*
这里也是多行注释，但是多行注释不能嵌套多行注释
*/
*/
System.out.println("多行注释不能嵌套多行注释");
}
总结：错误注释是一种伤害，必要注释是一种责任,不注释便是一种境界。
避免废话式注释
不要严重低估代码阅读者的智商，对于一些废话式的注释，应该极力避免。具体事例如下：
程序清单 2-1
/**
* 测试类
* @author 阿毅
* @date 2017/2/7.
*/
public class AyTest {
private int num;
//年份,默认值为0(废话式注释)
private int year;
//设置数量（废话式注释2）
public void setNum(int num) {
this.num = num;
}
@Test
public void test(){
//数量自增（废话式注释3）
num ++;
//如果num大于0，打印相关信息（废话式注释4）
if(num > 0){
System.out.println("num 大于0");
}else{
System.out.println("num 小于0");
}
}
}
时刻保持注释与代码的同步
由于需求的变化，开发者经常会修改相关的业务代码，但往往忘记同步修改相关的业务注释，造成业务注释和业务代码完全不沾边。所有在项目开发中，我们要时刻保持注释与代码的同步。修改了代码，头脑马上要想起来修改相关的注释。
代码注释，代码注释，代码注释，重要事情说3遍
读书感悟
来自《纳尼亚传奇》
- When you choose to become others, you will lose yourself.
当你选择成为别人，你将失去你自己. - I focus too much on what I lost, not what I have.
我太专注于我所失去的，忽略了我所拥有的. - You are nothing if you don’t believe！
如果没有信心，你就什么都不是！ - 你愿意和我并肩作战吗? Are you with me ?
至死不渝! To the death.
经典故事
【小鸡问母鸡：可否不用下蛋，带我出去玩啊？母鸡道：不行，我要工作！小鸡说：可你已经下了这么多蛋了！母鸡意味深长地对小鸡说：一天一个蛋，菜刀靠边站，一月不生蛋，高压锅里见。
存在是因为你创造价值，淘汰是因为你失去价值。过去的价值不代表未来，所以每天都要努力！】
大神文章
[1] Robert C.Martin. Clean Code: A Handbook of Agile Software [M]. Prentice Hall PTR,2008:50-69
[2] 秦小波. 编写高质量代码：改善Java程序的151个建议[M]. 北京：机械工业出版社，2012：300-301
其他
如果有带给你一丝丝小快乐，就让快乐继续传递下去，欢迎点赞、顶、欢迎留下宝贵的意见、多谢支持！
