2024年鸿蒙最全到底如何写好注释呢？来呀，看这里_程序注释怎么写(2)，2024年最新bash面试题

本文链接：https://blog.csdn.net/2401_84862416/article/details/138888351

网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

}


相信我们平时开发中，大多数都会写过上面这种注释，但其实上面的代码犯了两个错误：


1. 多余的注释：上面这个方法getTaskList已经能够通过方法名比较清晰的明白该方法的作用啦，就是获取任务列表。没必要再加注释，注释的作用是为了弥补代码表达的不足，不是每段代码都要加注释，反而是能用代码表达清晰的，就不必再加注释。
2. 误导性注释：既然你选择加注释，那就认真对待注释，加了可以起到效果，不要把注释写的模棱两可，或者可有可无，假如文件中还有一个获取其他列表的方法，那是不是就有歧义啦。


这里只是想强调一下，我们一定要认真对待注释，同时尽可能写的完整和清晰。否则很可能起到反作用。


##### 哪里都加注释


可能团队要求加注释了，于是乎就尽可能的能加注释就全部加了，不管有没有必要，哪里都加，这更是不推荐的，注释的维护也是有成本的，我们反而是应该能用代码表达的就只用代码，尽可能不用注释。


##### 日志式注释


有时候，有些文件可能修改比较频繁，于是会就把所有的修改记录全部添加到注释中，其实也是没有必要的，时间长了，只会越来越冗余。


![image.png](https://img-blog.csdnimg.cn/img_convert/4872a83e2e8be2d16b3ae02de9c1791a.png)


##### 注释掉的代码


这个大家肯定都做过，某些功能或者代码可能暂时需要隐藏，于是直接把对应的代码注释掉，对于自己来说，可能是更方便啦，但是对于别人啦，当别人看到一段代码注释掉啦，肯定有产生疑问？这段代码是否还有作用，能不能删等？而且注释的代码越多，整体代码质量就会越差。 ![image.png](https://img-blog.csdnimg.cn/img_convert/309df84e68120666949c19e9cd1ad614.png) 因此，如果有需要暂时隐藏的功能，我们直接把对应的功能删除即可，其实重新找回来也是很容易的，从git历史版本等可以很轻易的找出来。


##### 非本地注释


也就是说 我们写注释时，一定要确保描述了离它最近的代码，而不是在当前地方描述另外一个地方的代码。


##### 注释信息过多


注释的信息过多，也没人愿意看，不仅代码，注释也要简洁，能够说明问题即可。


![image.png](https://img-blog.csdnimg.cn/img_convert/4bc48fec609cac49cef945eb8b1203e4.png)


总结：以上不管是好注释还是坏注释，都可能是我们平时开发中，可能遇到的，也可能就是自己写的，我们通过这节的学习，至少知道了哪些注释是好的，哪些是坏的，以后，我们要可能避免写出这些还注释。总结起来一句话；`能用优雅的代码表达，就不要用注释，如果必须加注释，一定要认真去维护和书写注释。`


### 规范篇


#### 【必须】使用/\* … \*/进行多行注释

// bad case
// getNumber() return a new number
// @param {Number} number
// @return {Number} number
function getNumber(number) {
return number;
}

// good case
/*

getNumber() return a new number
*/
function getNumber(number) {
return number;
}


#### 【必须】 `/** ... */` 风格（首行有两个 \*）的块级多行注释仅能被用于 JSDoc。


也就是说：我们上面第一点提到的多行注释，首行是使用单\* 的，这种方式相当我们可以自定义的格式自由组织注释的内容，但是如果使用首行双\*的话，仅能被用于Jsdoc， Jsdoc是什么呢？官网链接如下：[JSDoc官网]( )， 简单理解为它就是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具。后面还会详细讲一下其使用。

// good case
/**

getNumber()
@description: 描述
@params {类型} 参数名 Must
@params {类型} 参数名 Optional
@returns {类型}
*/
function getNumber(number) {
return number;
}


**拓展：当我们写一些公共工具库或者函数的时候，可以推荐使用该JSDoc，可以帮助我们更规范的生成注释内容。**


#### 【推荐】使用//进行单行注释


除此之外，还有两点要注意：


1. 一般将单行注释放在需要被注释的行的上面新行。
2. 建议在注释之前放一个空行，除非它在块的第一行。


注意：通过前面的理论篇的学习，大家再看下面这些代码的时候，很可能产生这样一个疑问：下面好多代码的注释都是无用注释呀，本身命名已经很好的说明其含义啦，没必要再加注释，哈哈哈，是的，你说的非常对，也说明你掌握了对理论篇的内容哈，而下面的case只是从代码规范的角度，看注释放到哪里比较合适，以及注释的格式怎么样比较规范，而注释的具体内容，以及是否需要注释不是本节的关注点。

// bad case
const username = ‘kobe’; // username: 用户名

// good case
// username: 用户名
const username = ‘kobe’;

// bad case
function getNumber(number) {
console.log(‘get number…’);
// 把参数赋值给变量
const num = number;
return num;
}

// good case
function getNumber(number) {
console.log(‘get number…’);

// 把参数赋值给变量
const num = number;
return num;
}

// good case
function getNumber(number) {
// 获取number
console.log(‘get number…’);
const num = number;
return num;
}


#### 【必须】使用一个空格开始所有的注释，不管是单行还是多行。

// bad case
//username: 用户名
const username = ‘kobe’;

// good case
// username: 用户名
const username = ‘kobe’;

// bad case
/*
*getNumber() return a new number
*@params {Number} number
*@return {Number} number
/
function getNumber(number) {
return number;
}

// good case
/

getNumber() return a new number
@params {Number} number
@return {Number} number
*/
function getNumber(number) {
return number;
}


#### 【推荐】使用 // FIXME: 注释当前存在的问题


即如果发现代码中有一些可能存在的问题，或者需要重新讨论的问题，可以使用// FIXME: xxx 来注释。

// good case
function getNumber(number) {
// FIXME: 这里不应该使用全局变量num
num = 0;
return number;
}


#### 【推荐】 使用// TODO: 注释暂未实现或者待解决的问题

// good case
function getNumber(number) {
// TODO: 这里的状态需要单独维护起来，不应该使用魔术数字。
const status = 0;
return number;
}


### 实战篇


怎么添加注释，以及注释的基本格式等内容，我们在规范篇已经清楚啦，实战篇，我们主要围绕实际项目开发中，有哪些地方需要加注释展开。


#### 公共API添加注释


不管是vue还是react，项目中肯定会有一个专门utils文件夹去维护自定义的一些工具方法，这些方法我们要尽可能把注释加上，推荐使用j sdoc去添加注释。其次就是一定会有一个components目录去维护项目中的公共组件，那组件中定义的props，事件等也需要添加注释。


#### 每个模块文件头部都添加注释


这里指的是，平时业务项目开发中，一定会拆分成很多不同的模块，同时，由于项目的类型不同，例如电商，医疗等不同类型，就会涉及到很多专业名词，因此，建议`在每个模块的文件头部都使用多行注释，去说明当前模块是什么模块，以及包含哪些子模块等` 。当然，这一点是我个人的开发习惯，大家根据实际情况决定即可。