【优雅编程之道】之注释

开心一笑

【今天朋友当着我们的面甩一张卡给他媳妇，说随便刷，我们心想他何时变得这么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 list = new ArrayList<>();
    System.out.println("上面的变量s和集合list没有任何用处，无情删除吧");
    System.out.println("结束");
}

TODO注释的妙用

开发过程中，时常因为工期赶而没有时间写好代码。每个开发人员都有意识，这个功能以后要重构或优化，但往往之后就不了了之了。一个有用的注释就是TODO注释，具体如下：

程序清单 2-1    

@Test
public void test(){

    List userIds = new ArrayList<>();
    for(int i=0;i

单行注释和多行注释不要混用

虽然多行注释可以嵌套单行注释，但是我们不建议你这样混合用，具体实例如下：

程序清单 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

其他

如果有带给你一丝丝小快乐，就让快乐继续传递下去，欢迎点赞、顶、欢迎留下宝贵的意见、多谢支持！