远离不写注释的程序员

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

问：程序员最讨厌什么样的同事？答：不写注释问：程序员最讨厌干什么？答：写注释

这仿佛成了一个死循环

大家都有过这样的经历

灵感上来了，疯狂敲代码

大几百行写完

真有成就感

但是队友不高兴了

没注释看不明白

所以，现在是否写注释

已经从行业约束问题

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

行注释和块注释

一般注释就两种

行注释和块注释

针对不同的语言略有差异

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

就能浏览文档了

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

都体现在文档当中了

这个文档非常规范

可以遍历项目层次

清晰、干净

很多开源项目的说明书

都是用它做的

非常优秀

写注释的人不一定更优秀

但只要你写了

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

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

原文链接：https://mp.weixin.qq.com/s/0aA_p_8BaCzPWI-uZaJeKw