远离不写注释的程序员

写注释的程序员才是好程序员

问：程序员最讨厌什么样的同事？

答：不写注释

问：程序员最讨厌干什么？

答：写注释

这仿佛成了一个死循环

大家都有过这样的经历

灵感上来了，疯狂敲代码

大几百行写完

真有成就感

---

但是队友不高兴了

没注释看不明白

所以，现在是否写注释

已经从行业约束问题

降低到最基本的道德问题了

行注释和块注释

一般注释就两种

行注释和块注释

针对不同的语言略有差异

---

Java 用 //

SQL 用 --

XML 用

其他配置或脚本用 ##

都比较类似

然后部分语言支持块注释

类似

/* 这种首尾包围的形式 */

示范

 void test() {
  String data="小面同学我爱你"; // 原文
  SM3 sm3 = SmUtil.sm3(); // 声明加密类
  sm3.setSalt("xiaomian".getBytes()); // 加盐
  String secretText=sm3.digestHex(data); // 执行加密字符串
  System.out.println(secretText); // 输出结果
 }

有注释之后

整个代码理解会更清晰

但是实际工作中

除了部分复杂算法

其实没有必要写到这么细

所以大部分时候

都建议写文档注释

包括 类、属性、方法等

JavaDoc标记

Java语言有一套专门的注释规则

可以形成标准文档

写的时候类似这样

/**
 * 这是一个示例接口
 */
public interface IMessageService {

    /**
     * 这是一个示例方法
     * @param arg1 参数1
     * @param arg2 参数2
     * @return 返回值
     */
    int execute(String arg1, int arg2);

}

首先它采用了 /* */ 块注释的变体形式

并且还有一些特殊的元素

类似注解

他们有一些特殊含义

类说明

写在类名之上

用于类的声明

/**
 * 消息服务接口
 * @author 王小面
 * @version 1.0.12
 */
public class IMessageService{
    ...
}

第一句 “消息服务接口” 代表功能阐述

下面两个元素都很容易理解

@author 代表作者

@version 代表版本

这是在早期年代流传下来的标记

可以用于声明主权

现在作用不大

完全可以用git解决

方法声明

写在方法名的上方

public class Test{
    /**
     * 求输入两个参数中最大的值
     * @param a 参与比较的第一个数
     * @param b 参与比较的第二个数
     * @return 两数之中较大的数
     */
    public int maxVal(int a, int b) {
        int max=0;
        if(a>b){
            max=a;
        }else{
            max=b;
        }
        return max;
    }
} 

首先用一句话阐述方法的功能

即“求输入两个参数中最大的值”

@param 代表入参说明

依次解释每个参数的意义

@return 代表返回值说明

这样就对整个功能有个概括的描述了

而没有必要每一行都做解释

---

如果注释内容较多

还可以使用标记语言

例如

/**
 * 这是一个测试方法<br>
 * 用于描述一些复杂的功能
 * @author Java技术教程<br>
 *         王小面
 */
public class Test {

}

一些常用的HTML语法都能使用

在源代码中是看不出效果的

但是一旦导出JavaDoc 文档

就能看出来了

导出JavaDoc

可以通过 javadoc 命令

生成标准的项目手册

可以通过IDE直接导出即可

个别同学可能会出现乱码

这是因为我们的电脑环境为GBK

而源码用的utf-8导致的

只需要声明

-encoding UTF-8 -charset UTF-8

查阅文档

打开导出目录下的index.html

就能浏览文档了

可以看到前面我们所写的注释

都体现在文档当中了

这个文档非常规范

可以遍历项目层次

清晰、干净

很多开源项目的说明书

都是用它做的

非常优秀

---

写注释的人不一定更优秀

但只要你写了

就会更加注重代码的可读性、可维护性

帮助其他开发人员更好地理解代码的功能