前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >远离不写注释的程序员

远离不写注释的程序员

作者头像
灬沙师弟
发布2023-09-06 08:21:01
1760
发布2023-09-06 08:21:01
举报
文章被收录于专栏:Java面试教程

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

代码语言:javascript
复制
问:程序员最讨厌什么样的同事?

答:不写注释

问:程序员最讨厌干什么?

答:写注释

这仿佛成了一个死循环

大家都有过这样的经历

灵感上来了,疯狂敲代码

大几百行写完

真有成就感

但是队友不高兴了

没注释看不明白

所以,现在是否写注释

已经从行业约束问题

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

行注释和块注释

一般注释就两种

行注释和块注释

针对不同的语言略有差异

Java 用 //

SQL 用 --

XML 用

其他配置或脚本用 ##

都比较类似

然后部分语言支持块注释

类似

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

示范

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

有注释之后

整个代码理解会更清晰

但是实际工作中

除了部分复杂算法

其实没有必要写到这么细

所以大部分时候

都建议写文档注释

包括 类、属性、方法等

JavaDoc标记

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

可以形成标准文档

写的时候类似这样

代码语言:javascript
复制
/**
 * 这是一个示例接口
 */
public interface IMessageService {

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

}

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

并且还有一些特殊的元素

类似注解

他们有一些特殊含义

类说明

写在类名之上

用于类的声明

代码语言:javascript
复制
/**
 * 消息服务接口
 * @author 王小面
 * @version 1.0.12
 */
public class IMessageService{
    ...
}

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

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

@author 代表作者

@version 代表版本

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

可以用于声明主权

现在作用不大

完全可以用git解决

方法声明

写在方法名的上方

代码语言:javascript
复制
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 代表返回值说明

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

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

如果注释内容较多

还可以使用标记语言

例如

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

}

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

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

但是一旦导出JavaDoc 文档

就能看出来了

导出JavaDoc

可以通过 javadoc 命令

生成标准的项目手册

可以通过IDE直接导出即可

个别同学可能会出现乱码

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

而源码用的utf-8导致的

只需要声明

代码语言:javascript
复制
-encoding UTF-8 -charset UTF-8

查阅文档

打开导出目录下的index.html

就能浏览文档了

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

都体现在文档当中了

这个文档非常规范

可以遍历项目层次

清晰、干净

很多开源项目的说明书

都是用它做的

非常优秀

写注释的人不一定更优秀

但只要你写了

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

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

本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2023-08-25,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 Java面试教程 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 写注释的程序员才是好程序员
  • 行注释和块注释
  • 示范
  • JavaDoc标记
    • 类说明
      • 方法声明
      • 导出JavaDoc
      • 查阅文档
      领券
      问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档