HarmonyOS Development: ArkTs Language Annotation

Foreword

this article excerpt is mainly about ArkTs language annotation related, all cases are based on api13.

The so-called comments, in program development, is for a piece of code to explain the annotation, good comments it can improve the readability of the code and allow the maintainers of the code to intervene more quickly. For example, if we take out the previous code, if we are a beginner, we need to look through the data to understand the function and meaning of each attribute.

Text(this.message)
        .fontSize(50)
        .fontWeight(FontWeight.Bold)

But with comments, you can intuitively see the meaning of each attribute, which is the role of comments.

Text(this.message)//设置展示的内容
        .fontSize(50)//设置文字大小
        .fontWeight(FontWeight.Bold)//设置文字字重

In actual development, being able to use comments correctly and appropriately is a necessary skill for every developer. Although it is said that no comments will not affect the execution of the program, others may not be able to understand the code you write in a short time. Moreover, you can guarantee that after the baptism of time, such as six months, one year, two years later, can you still know the relevant logic of the code at this time? Therefore, in order to continue to maintain the code without obstacles for oneself and others, it is suggested that comments should be added.

ArkTs provides us with two annotation methods, one is single-line annotation and the other is multi-line annotation.

Single-line comment

it is used to briefly explain a line of code, starting with //. In the preface, we use single-line comments. When the project is created, you can check it in EntryAbility. Basically, single-line comments are also the main ones.

Simple example

const a = 1 //声明一个常量a 赋值为1
const b = 2 //声明一个常量b 赋值为2
const c = a + b //声明一个常量c 赋值为 a+b 的和
//打印常量c的值
 console.log("===" + c)

multi-line comment

It is used to comment on multi-line code or long instructions, starting with/* and ending with */. The places where multi-line comments are used are also very common. The method and class comments described below are all multi-line comments. When we open the source code of a system casually, we will see such comments.

Simple example

/*
 *以下的代码是用来计算常量a+常量b的和，
 * 然后通过console进行打印出结果
 **/
const a = 1
const b = 2
const c = a + b
console.log("===" + c)

of course, you can also omit the extra "*" in the middle.

/*
 以下的代码是用来计算常量a+常量b的和，
 然后通过console进行打印出结果
*/
const a = 1
const b = 2
const c = a + b
console.log("===" + c)

Variable comment

variable comments can use single-line comments, multi-line comments and multi-line comments. The description of variables is clearer and more detailed. We can open the Api of the system and find that most of the systems are based on multi-line comments.

Of course, in development, it does not mean that we should also follow such rules. We can selectively use single-line and multi-line variables according to the simplicity of variables. In general, local variables are mainly single-line Variables. If they are member variables, they can be single-line or multi-line.

Local variable, single line comment:

const a = 1 //声明一个常量a 赋值为1

member variable, single-line comment:

@State message: string = '测试代码' //Text组件展示的内容

member variables, multi-line comments, you can set the variable type and applicable version and other information:

  /**
   * 是否显示
   * @type { boolean }
   * @since 11
   */
  isShow?: boolean

function comments

in fact, function comments are also a kind of multi-line comments, which are used to explain the specific description of a function. As for what a function is, we will focus on the following chapter "Understanding Functions". Here, we will only explain the relevant comments, such as defining a summation function casually:

  add(a: number, b: number) {
    const c = a + b
    console.log("===" + c)
  }

Experienced people may know the function of the above functions at a glance, but for beginners, they need to understand. For such simple functions, it is easy to understand, especially for those complex functions with many parameters, it is difficult to understand without a comment. Therefore, in daily development, it is strongly recommended that everyone must comment on complex functions.

Function comments generally need to describe the function of this function, that is, what this function is used to do, and also, to mark the parameters and types passed, and whether there is a return value. Finally, remember to mark whether the current function is in normal use or expired state. We might as well look at the comments of the system Api on the function.

Then based on the above conditions, we add the sum function just now to the annotation.

/**
   * 求两个值的和
   * @param { number } a 任意 number 类型参数
   * @param { number } b 任意 number 类型参数
   */
  add(a: number, b: number) {
    const c = a + b
    console.log("===" + c)
  }

When there are comments, when we click on the method with the left button, we can intuitively know the intention of the method.

In addition to the normal comments, we can also mark the applicable version number of the current method and whether it has expired, so that the caller can understand it more clearly.

To mark the version number, use @ since.

/**
   * 求两个值的和
   * @param { number } a 任意 number 类型参数
   * @param { number } b 任意 number 类型参数
   * @since 12
   */
  add(a: number, b: number) {
    const c = a + b
    console.log("===" + c)
  }

The annotation method is obsolete, use @ deprecated.

/**
   * 求两个值的和
   * @param { number } a 任意 number 类型参数
   * @param { number } b 任意 number 类型参数
   * @since 12
   * @deprecated
   */
  add(a: number, b: number) {
    const c = a + b
    console.log("===" + c)
  }

When the annotation expires, the strikethrough state will appear when calling the method, as follows:

in addition to the normal parameter annotation, there is also a function with a return value. For example, we modify the above function and return it with the @ returns annotation.

  /**
   * 求两个值的和
   * @param { number } a 任意 number 类型参数
   * @param { number } b 任意 number 类型参数
   * @returns { number } 返回两个number类型数据相加的和
   */
  add(a: number, b: number): number {
    return a + b
  }

Class Annotation

The so-called class annotation is actually quite different from the method annotation. It also mainly describes the function of the current class. Of course, in actual development, in addition to the description function, there are generally information such as the creator and time, which is convenient for subsequent maintainers to quickly communicate and find problems. The specific parameter definition can be defined according to the developer's preference or the company's definition. In general, the style of a project, unity must be maintained.

The following is a very common class annotation.

/**
 * AUTHOR:AbnerMing
 * DATE:2025/01/16
 * INTRODUCE:测试类，主要用于测试
 * */
export class Test {

}

In the class annotation, you can also set the version, or whether it expires, or that sentence, and analyze the specific problems.

Annotation Template

if you have to manually write comments every time you create a class or a method, it is obviously very tedious. Fortunately, there are convenient methods provided in IDE, that is, templates. Using templates can easily implement comments and completely free our hands.

Method annotation

on the method that needs to be annotated, we can type/* *, and then enter. A method annotation will be automatically generated for us, but it is not complete, and we need to write instructions and other information ourselves.

The dynamic effects are as follows:

class Annotation

the class annotation template is not available by default. However, we can add it in IDE settings, open the Settings page, find the Editor option, click File and Code Templates, find the ArkTs File option, and after clicking, we can write our class annotation on the right.

Since there is no class for us to create ets files by default, we can also set it here, set it up, click OK, and then when creating ets files, class comments will be automatically added, as shown in the following figure.

Summary

regarding comments, one thing to note is that comments will not be executed by compilers or interpreters, and the focus of this section is not simply to teach you how to write comments, but in actual projects, we can really put comments into actual development.

The group of programmers is very strange. They have two major haters against comments. One is that they hate that others do not write comments when maintaining other people's code. The other is that they let themselves write comments when writing their own code.

In any case, I hope that in studying this article, you can carry the banner of programmer annotation and let the annotation flourish!