【优雅编程之道】之注释的9点建议

2019-11-08 02:10:29

字体：大中小

来源：转载

供稿：网友

开心一笑

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

TODO注释的妙用

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

程序清单 2-1 @Testpublic 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 @Testpublic 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