前言
本篇文章节选于主要讲述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文件的时候,类注释就自动添加上了,
如下图所示。
小结
关于注释,有一点需要注意,那就是,注释,不会被编译器或解释器执行,而本小节的重点并不是简单的教大家注释如何去写,而是在实际的项目中,我们能够真正的把注释投入到实际的开发中。
程序员这个群体很奇怪,他们针对注释有两大讨厌,一是讨厌在维护别人代码的时候,讨厌别人不写注释,二是,自己写代码的时候,让自己写注释。
不管如何,我是希望,在学习这篇文章你,能够扛起程序员注释大旗,让注释能够发扬光大!