鸿蒙开发:ArkTs语言注释

简介: 关于注释,有一点需要注意,那就是,注释,不会被编译器或解释器执行,而本小节的重点并不是简单的教大家注释如何去写,而是在实际的项目中,我们能够真正的把注释投入到实际的开发中。

前言


本篇文章节选于主要讲述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文件的时候,类注释就自动添加上了,

如下图所示。


小结


关于注释,有一点需要注意,那就是,注释,不会被编译器或解释器执行,而本小节的重点并不是简单的教大家注释如何去写,而是在实际的项目中,我们能够真正的把注释投入到实际的开发中。


程序员这个群体很奇怪,他们针对注释有两大讨厌,一是讨厌在维护别人代码的时候,讨厌别人不写注释,二是,自己写代码的时候,让自己写注释。


不管如何,我是希望,在学习这篇文章你,能够扛起程序员注释大旗,让注释能够发扬光大!

目录
打赏
0
18
18
0
180
分享
相关文章
鸿蒙开发:权限管理之权限声明
本文,主要简单概述了为什么要有权限管理,以及权限管理的声明原则,这些都是基本的概念内容,大家做为了解即可,重要的是怎么声明权限,在什么位置声明权限,这一点需要掌握。
35 16
鸿蒙开发:权限管理之权限声明
鸿蒙开发:console日志输出
针对初学者而言,大家只需要掌握住日志打印即可,等到了鸿蒙应用开发的时候,还有一个鸿蒙原生的打印工具HiLog,到时,我们也会详细的去讲述,也会针对HiLog,封装一个通用的工具类。
25 11
鸿蒙开发:console日志输出
鸿蒙开发:ArkTs语言变量和常量
变量是一种用于存储数据的容器,并且其存储的数据值可以在程序执行过程中被改变,变量通常有一个名字(标识符),用于在程序中引用它。
|
10天前
鸿蒙开发:V2版本装饰器@Once
@Once装饰器只能与@Param搭配使用,仅此一个组合,无其他使用方式,还有就是,必须在V2版本,也就是@ComponentV2装饰的自定义组件中,否则会报异常。
鸿蒙开发:V2版本装饰器@Once
uniapp 极速上手鸿蒙开发
uniapp 自版本 `4.28.2024092502` 起支持鸿蒙应用开发,现版本 `4.36.2024112817` 同时支持鸿蒙应用和元服务开发。本文介绍使用 HBuilderX 4.24+ 和 DevEco Studio 进行环境配置、项目创建及运行的详细步骤,涵盖从 AGC 平台新建项目、配置证书到最终运行项目的全流程,帮助开发者快速上手鸿蒙开发。注意:HBuilderX 4.31+ 构建的鸿蒙运行包不支持 x86_64 平台,需使用真机调试。
109 85
uniapp 极速上手鸿蒙开发
|
4天前
鸿蒙开发:wrapBuilder传递参数
本文,主要简单了介绍了一下,非UI使用的情况下,wrapBuilder传递数据问题,除了以上的方式之外,还有其它的方式可以实现,在实际的开发中,还是具体问题具体分析。
77 61
鸿蒙开发:wrapBuilder传递参数
|
3天前
|
鸿蒙开发:自定义一个搜索模版
这样的一个模版,可以简单的分为,三个部分,分别是上边的搜索框,中间的历史搜索和下边的热门搜索,搜索框,我们直接可以使用系统的组件Search,历史搜索,由于是内容不一的搜索的内容,这里使用弹性布局Flex,下边的热门搜索,条目规格一致,这里我们直接使用Grid网格组件。
40 23
鸿蒙开发:自定义一个搜索模版
|
2天前
|
鸿蒙开发:了解应用级配置信息
在实际的开发中,如果有共用的资源,建议大家都放到AppScope目录下,对于一些应用级别的信息,比如应用的名字,还有应用的图标,虽然说在Moulde下也可以配置,但是为了更方便的管理,这里比较推荐以AppScope目录下的app.json5为主,当然了,只是推荐,实际当中,两者都可以实现,大家选择其中一种方式即可。
25 12
鸿蒙开发:了解应用级配置信息
鸿蒙开发:弹性布局Flex
在实际的开发中,需要掌握主轴与交叉轴的关系、换行规则及子元素属性,同时注意性能与兼容性问题,还有一点,Flex组件在渲染时存在二次布局过程,因此在对性能有严格要求的场景下建议使用Column、Row代替。
26 10
鸿蒙开发:弹性布局Flex
|
8天前
|
鸿蒙开发:实现AOP代码插桩能力
正确的运用AOP,可以提升代码的模块化、复用性、可维护性和灵活性,同时降低了耦合度,使系统更易于扩展和维护。
37 13
鸿蒙开发:实现AOP代码插桩能力

热门文章

最新文章

AI助理

你好,我是AI助理

可以解答问题、推荐解决方案等