前言
本篇文章节选于主要讲述ArkTs语言注释相关，所有案例均基于Api13。
所谓注释，在程序开发中，就是针对一段代码进行标注解释，好的注释能够提高代码的可读性，让代码的维护者能更快的介入，比如我们把前面的代码拿出来，如果是一个初学者，就需要翻阅资料进行了解每一个属性的作用和意思。
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
但是有了注释之后，就很能直观的看出每一个属性的意思，这就是注释的作用。
Text(this.message)//设置展示的内容
.fontSize(50)//设置文字大小
.fontWeight(FontWeight.Bold)//设置文字字重
在实际的开发中，能够正确恰当的使用注释，是每一个开发者必备的技能，虽然说，没有注释也不影响程序的执行，但是你写的代码，他人未必能够短时间的了解，再者，你能保证，经过时间的洗礼，比如过了半年，一年，两年之后，此时的代码，你还能知道相关逻辑吗？所以，为了自身和他人能够无障碍的继续维护代码，建议，注释还是要添加的。
ArkTs中为我们提供了两种注释方式，一种是单行注释，另一种是多行注释。
单行注释
用于对某一行代码进行简单说明，以 // 开头，在前言中，我们就是使用的单行注释，在项目创建的时候，大家可以去EntryAbility中查看下，基本上也是以单行注释为主。
简单举例
const a = 1 //声明一个常量a 赋值为1
const b = 2 //声明一个常量b 赋值为2
const c = a + b //声明一个常量c 赋值为 a+b 的和
//打印常量c的值
console.log("===" + c)
多行注释
用于对多行代码或较长的说明进行注释，以 /* 开始，以 */ 结尾，多行注释使用的地方也是非常的常见，像下面所阐述的方法和类注释等都是属于多行注释，当我们随便打开一个系统的源码，都会看到这样的注释。
简单举例
/*
*以下的代码是用来计算常量a+常量b的和，
* 然后通过console进行打印出结果
**/
const a = 1
const b = 2
const c = a + b
console.log("===" + c)
当然了，中间多出的“*”，你也可以省略。
/*
以下的代码是用来计算常量a+常量b的和，
然后通过console进行打印出结果
*/
const a = 1
const b = 2
const c = a + b
console.log("===" + c)
变量注释
变量注释，可以使用单行注释，也可以使用多行注释，多行注释，针对变量的说明更加清晰，更加细致，我们可以打开系统的Api，可以发现，系统大部分也都是基于多行注释。
当然了，在开发中，并不意味着，我们也要遵循这样的规则，我们可以根据变量的简单与否，单行和多行进行选择性使用，一般情况下，局部变量，以单行为主，如果是成员变量，则可单行也可多行。
局部变量，单行注释：
const a = 1 //声明一个常量a 赋值为1
成员变量，单行注释：
@State message: string = '测试代码' //Text组件展示的内容
成员变量，多行注释，可以设置变量类型以及可适用版本等信息：
/**
* 是否显示
* @type { boolean }
* @since 11
*/
isShow?: boolean
函数注释
其实函数注释也是多行注释的一种，用于解释一个函数的具体说明，至于什么是函数，在之后的《了解函数》一章中会重点概述，这里，我们只讲解关于注释相关的，比如我们随便定义一个求和的函数：
add(a: number, b: number) {
const c = a + b
console.log("===" + c)
}
有经验的人，可能一眼就能知道上述函数的作用，但是对于初学者而言就需要进行理解了，对于这样的简单的函数到还容易明白，特别是那些复杂，参数众多的函数，如果没有一个注释，是很难进行理解的，所以，在日常的开发中，是强烈建议，大家针对复杂的函数，必须进行注释的。
函数注释，一般需要描述此函数的作用，也就是这个函数是用来做什么的，还有就是，标注传递的参数及类型，以及是否具有返回值，最后，记得标注当前函数是正常使用还是已过期状态，我们不妨看下系统Api关于函数的注释。
那么基于以上的条件，我们把刚才的求和函数，加上注释。
/**
* 求两个值的和
* @param { number } a 任意 number 类型参数
* @param { number } b 任意 number 类型参数
*/
add(a: number, b: number) {
const c = a + b
console.log("===" + c)
}
当有注释的时候，我们在左键点击方法的时候，可以很直观的就能知道方法的意图。
除了正常的注释之外，我们也可以标注当前方法的适用版本号，以及是否过期等注释，便于调用者更加清晰的了解。
标注版本号，使用@since。
/**
* 求两个值的和
* @param { number } a 任意 number 类型参数
* @param { number } b 任意 number 类型参数
* @since 12
*/
add(a: number, b: number) {
const c = a + b
console.log("===" + c)
}
标注方法过时，使用@deprecated。
/**
* 求两个值的和
* @param { number } a 任意 number 类型参数
* @param { number } b 任意 number 类型参数
* @since 12
* @deprecated
*/
add(a: number, b: number) {
const c = a + b
console.log("===" + c)
}
当标注了过期之后，在调用方法的时候就会出现删除线状态，如下：
除了正常的参数注释之外，还有一种情况是带有返回值的函数，比如，我们把上面的函数改造一下，然后使用@returns标注返回。
/**
* 求两个值的和
* @param { number } a 任意 number 类型参数
* @param { number } b 任意 number 类型参数
* @returns { number } 返回两个number类型数据相加的和
*/
add(a: number, b: number): number {
return a + b
}
类注释
所谓的类注释，和方式注释其实大差不差，也是主要描述当前类的作用，当然，在实际的开发中，除了描述作用之外，一般还有创建者，时间等信息，便于后续的维护者进行快速的沟通和问题的查找，具体的参数定义，可以按照开发者喜好或者公司定义而来，一般情况下，一个项目的风格，务必要保持统一。
如下，就是一个很常见的类注释。
/**
* AUTHOR:AbnerMing
* DATE:2025/01/16
* INTRODUCE:测试类，主要用于测试
* */
export class Test {
}
类注释中，大家也可以进行版本的设置，或者是否过期等设置，还是那句话，具体问题具体分析。
注释模版
如果每创建一个类或者创建一个方法都要手动写上注释，显然是非常繁琐的，还好，IDE中有便捷方法的提供，也就是模版，使用模版可以很方便的实现注释，彻底解放我们的双手。
方法注释
在需要添加注释的方法上边，我们打上/**，然后回车即可，一个方法注释就给我们自动生成好了，但是并不完整，还需要我们自己书写说明等信息。
动态效果如下：
类注释
类注释模版，默认是没有的，不过，我们可以在IDE设置中进行添加，打开设置页面，找到Editor选项，点击File and Code Templates，找到ArkTs File选项，点击后，我们就可以在右边编写我们的类注释了。
由于默认情况下，我们创建ets文件是没有class的，我们也可以在这里进行设置，设置好，点击OK，以后在创建ets文件的时候，类注释就自动添加上了，如下图所示。
小结
关于注释，有一点需要注意，那就是，注释，不会被编译器或解释器执行，而本小节的重点并不是简单的教大家注释如何去写，而是在实际的项目中，我们能够真正的把注释投入到实际的开发中。
程序员这个群体很奇怪，他们针对注释有两大讨厌，一是讨厌在维护别人代码的时候，讨厌别人不写注释，二是，自己写代码的时候，让自己写注释。
不管如何，我是希望，在学习这篇文章你，能够扛起程序员注释大旗，让注释能够发扬光大！
Top comments (0)