# ArkTS编程规范

## 目标和适用范围

本文参考业界标准和实践，结合ArkTS语言特点，提供编码指南，以提高代码的规范性、安全性和性能。

本文适用于使用ArkTS编写的开发场景。

## 规则来源

ArkTS在保持TypeScript基本语法风格的基础上，进一步强化静态检查和分析。本文部分规则筛选自《[OpenHarmony应用TS&JS编程指南](https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/OpenHarmony-Application-Typescript-JavaScript-coding-guide.md)》，为ArkTS语言新增的语法添加了规则，旨在提高代码可读性、执行性能。

## 章节概览

### 代码风格

包含命名和格式。

### 编程实践

包含声明与初始化、数据类型、运算与表达式、异常等。

参考了《OpenHarmony应用TS&JS编程指南》中的规则，去除了ArkTS语言不涉及的部分，并为新增的语法添加了规则。

## 术语和定义

|术语|缩略语|中文解释|
|:---------|:--|:-----------------------------|
|ArkTS|无|ArkTS编程语言|
|TypeScript|TS|TypeScript编程语言|
|JavaScript|JS|JavaScript编程语言|
|ESObject|无|在ArkTS跨语言调用的场景中，用以标注JS/TS对象的类型|

## 总体原则

规则分为两个级别：要求和建议。

**要求**：表示原则上应该遵从。本文所有内容目前均为针对ArkTS的要求。

**建议**：表示该条款属于最佳实践，可结合实际情况考虑是否纳入。

## 命名

### 为标识符取一个好名字，提高代码可读性

**【描述】**

好的标识符命名应遵循以下原则：

* 清晰表达意图，避免使用单个字母或非标准缩写命名。
* 使用正确的英文单词并符合英文语法，不要使用中文拼音。
* 确保语句清晰，避免歧义。

### 类名、枚举名、命名空间名采用UpperCamelCase风格

**【级别】建议**

**【描述】**

类采用首字母大写的驼峰命名法。

类名通常是名词或名词短语，例如Person、Student、Worker。不应使用动词，也应该避免类似Data、Info这样的模糊词。

**【正例】**

```TypeScript
// 类名
class User {
  username: string

  constructor(username: string) {
    this.username = username;
  }

  sayHi() {
    console.info('hi' + this.username);
  }
}

// 枚举名
enum UserType {
  TEACHER = 0,
  STUDENT = 1
};

// 命名空间
namespace Base64Utils {
  export function encrypt() {
    // todo encrypt
  }

  export function decrypt() {
    // todo decrypt
  }
};
```

### 变量名、方法名、参数名采用lowerCamelCase风格

**【级别】建议**

**【描述】**

函数的命名通常是动词或动词短语，采用小驼峰命名。示例如下：

1. load + 属性名()
2. put + 属性名()
3. is + 布尔属性名()
4. has + 名词/形容词()
5. 动词()
6. 动词 + 宾语()

变量名通常是名词或名词短语，采用小驼峰命名，便于理解。

**【正例】**

```TypeScript
let msg = 'Hello world';

function sendMsg(msg: string) {
  // todo send message
  // ...
}

let userName = 'Zhangsan';

function findUser(userName: string) {
  // todo find user by user name
  // ...
}
```

### 常量名、枚举值名采用全部大写，单词间使用下划线隔开

**【级别】建议**

**【描述】**

常量命名，应该由全大写单词与下划线组成，单词间用下划线分隔。常量命名要尽量表达完整的语义。

**【正例】**

```TypeScript
const MAX_USER_SIZE = 10000;

enum UserType1 {
  TEACHER = 0,
  STUDENT = 1
};
```

### 避免使用否定的布尔变量名，布尔型的局部变量或方法需加上表达是非意义的前缀

**【级别】建议**

**【描述】**

布尔型的局部变量建议加上表达是非意义的前缀，比如is，也可以是has、can、should等。但是，当使用逻辑非运算符，并出现双重否定时，会出现理解问题，比如!isNotError，难以理解。因此，应避免定义否定的布尔变量名。

**【反例】**

```TypeScript
let isNoError = true;
let isNotFound = false;

function empty() {}
function next() {}
```

**【正例】**

```TypeScript
let isError = false;
let isFound = true;

function isEmpty() {}
function hasNext() {}
```

## 格式

### 使用空格缩进，禁止使用tab字符

**【级别】建议**

**【描述】**

只允许使用空格(space)进行缩进。

建议大部分场景优先使用2个空格，换行导致的缩进优先使用4个空格。

不允许插入制表符Tab。当前几乎所有的集成开发环境（IDE）和代码编辑器都支持配置将Tab键自动扩展为2个空格输入，应在代码编辑器中配置使用空格进行缩进。

**【正例】**

```TypeScript
class DataSource {
  id: number = 0
  title: string = ''
  content: string = ''
}

const dataSource: DataSource[] = [
  {
    id: 1,
    title: 'Title 1',
    content: 'Content 1'
  },
  {
    id: 2,
    title: 'Title 2',
    content: 'Content 2'
  }

];

function test(dataSource: DataSource[]) {
  if (!dataSource.length) {
    return;
  }

  for (let data of dataSource) {
    if (!data || !data.id || !data.title || !data.content) {
      continue;
    }
    // some code
  }

  // some code
}
```

### 行宽不超过120个字符

**【级别】建议**

**【描述】**

代码行宽不宜过长，否则不利于阅读。

控制行宽可以间接引导程序员缩短函数和变量的命名，减少嵌套层数，精炼注释，从而提升代码可读性。

建议每行字符数不超过120个，除非需要显著增加可读性（超过120个），且不会隐藏信息。

例外：如果一行注释包含了超过120个字符的命令或URL，则可以保持一行，以方便复制、粘贴和通过grep查找；预处理的error信息在一行便于阅读和理解，即使超过120个字符。

### 条件语句和循环语句的实现建议使用大括号

**【级别】建议**

**【描述】**

在if、for、do、while等语句的执行体加大括号{}是一种最佳实践，因为省略大括号可能导致错误，并且降低代码的清晰度。

**【反例】**

```TypeScript
let condition = true;
if (condition)
  console.info('success');
for (let idx = 0; idx < 5; ++idx)
  console.info('', idx);
```

**【正例】**

```TypeScript
let condition = true;
if (condition) {
  console.info('success');
}
for (let idx = 0; idx < 5; ++idx) {
  console.info('', idx);
}
```

### switch语句的case和default需缩进一层

**【级别】建议**

**【描述】**

switch的case和default要缩进一层（2个空格）。开关标签之后换行的语句，需再缩进一层（2个空格）。

**【正例】**

```TypeScript
switch (condition) {
  case 0: {
    doSomething();
    break;
  }
  case 1: {
    doOtherthing();
    break;
  }
  default:
    break;
}
```

### 表达式换行需保持一致性，运算符放行末

**【级别】建议**

**【描述】**

当语句过长或可读性不佳时，需要在合适的地方进行换行。

换行时将操作符放在行末，表示"未结束，后续还有"，保持与常用的格式化工具的默认配置一致。

**【正例】**

```TypeScript
// 假设条件语句超出行宽
if (userCount > MAX_USER_COUNT ||
  userCount < MIN_USER_COUNT) {
  doSomething();
}
```

### 多个变量定义和赋值语句不允许写在一行

**【级别】要求**

**【描述】**

每个语句的变量声明都应只声明一个变量。

这种方式更便于添加变量声明，无需考虑将分号改为逗号，以免引入错误。此外，每个语句只声明一个变量，使用调试器逐个调试也很方便，而不是一次跳过所有变量。

**【反例】**

```TypeScript
let maxCount = 10, isCompleted = false;
let pointX, pointY;
pointX = 10; pointY = 0;
```

**【正例】**

```TypeScript
let maxCount = 10;
let isCompleted = false;
let pointX = 0;
let pointY = 0;
```

### 空格应该突出关键字和重要信息，避免不必要的空格

**【级别】建议**

**【描述】**

空格应该突出关键字和重要信息。总体建议如下：

1. if, for, while, switch等关键字与左括号(之间加空格。
2. 在函数定义和调用时，函数名称与参数列表的左括号(之间不加空格。
3. 关键字else或catch与其之前的大括号}之间加空格。
4. 任何打开大括号({)之前加空格，有两个例外：
   * 在作为函数的第一个参数或数组中的第一个元素时，对象之前不用加空格，例如：foo({ name: 'abc' })。
   * 在模板中，不用加空格，例如：abc${name}。
5. 二元操作符(+ - * = < > <= >= === !== && ||)前后加空格；三元操作符(? :)符号两侧均加空格。
6. 数组初始化中的逗号和函数中多个参数之间的逗号后加空格。
7. 在逗号(,)或分号(;)之前不加空格。
8. 数组的中括号([])内侧不要加空格。
9. 不要出现多个连续空格。在某行中，多个空格若不是用来作缩进的，通常是个错误。

**【反例】**

```TypeScript
  // if 和左括号 ( 之间没有加空格
  if(isJedi) {
    fight();
  }
  // ...
// 函数名fight和左括号 ( 之间加了空格
function fightBad (): void {
  console.info('Swooosh!');
}
```

**【正例】**

```TypeScript
  // if 和左括号之间加一个空格
  if (isJedi) {
    fight();
  }
  // ...
// 函数名fight和左括号 ( 之间不加空格
function fight(): void {
  console.info('Swooosh!');
}
```

**【反例】**

```TypeScript
if (flag) {
  // ...
}else { // else 与其前面的大括号 } 之间没有加空格
  // ...
}
```

**【正例】**

```TypeScript
if (flag) {
  // ...
} else { // else 与其前面的大括号 } 之间增加空格
  // ...
}
```

**【正例】**

```TypeScript
function foo() { // 函数声明时，左大括号 { 之前加个空格
  // ...
}

bar('attr', { // 左大括号前加个空格
  age: '1 year',
  sbreed: 'Bernese Mountain Dog',
});
```

**【正例】**

```TypeScript
const arr = [1, 2, 3]; // 数组初始化中的逗号后面加个空格，逗号前面不加空格
myFunc(bar1, foo1, baz); // 函数的多个参数之间的逗号后加个空格，逗号前面不加空格
```

### 建议字符串使用单引号

**【级别】建议**

**【描述】**

为了保持代码一致性和可读性，建议使用单引号。

**【反例】**

```TypeScript
let message1 = "world";
console.info(message1);
```

**【正例】**

```TypeScript
let message2 = 'world';
console.info(message2);
```

### 对象字面量属性超过4个，需要都换行

**【级别】建议**

**【描述】**

对象字面量的属性应保持一致的格式：要么每个属性都换行，要么所有属性都在同一行。当对象字面量的属性超过4个时，建议统一换行。

**【反例】**

```TypeScript
interface I {
  name: string
  age: number
  value: number
  sum: number
  foo: boolean
  bar: boolean
}

let obj1: I = { name: 'tom', age: 16, value: 1, sum: 2, foo: true, bar: false }
```

**【正例】**

```TypeScript
interface I {
  name: string
  age: number
  value: number
  sum: number
  foo: boolean
  bar: boolean
}

// ...
let obj2: I = {
  name: 'tom',
  age: 16,
  value: 1,
  sum: 2,
  foo: true,
  bar: false
}
```

### 把else/catch放在if/try代码块关闭括号的同一行

**【级别】建议**

**【描述】**

编写条件语句时，建议将else放在if代码块关闭括号的同一行。同样，编写异常处理语句时，建议将catch放在try代码块关闭括号的同一行。

**【反例】**

```TypeScript
if (isOk) {
  doThing1();
  doThing2();
}
else {
  doThing3();
}
```

**【正例】**

```TypeScript
if (isOk) {
  doThing1();
  doThing2();
} else {
  doThing3();
}
```

**【反例】**

```TypeScript
try {
  doSomething();
}
catch (err) {
  // 处理错误
}
```

**【正例】**

```TypeScript
try {
  doSomething();
} catch (err) {
  // 处理错误
}
```

### 大括号{和语句在同一行

**【级别】建议**

**【描述】**

应保持一致的大括号风格。建议将大括号置于控制语句或声明语句的同一行。

**【反例】**

```TypeScript
function foo1()
{
  // ...
}
```

**【正例】**

```TypeScript
function foo2() {
  // ...
}
```

## 编程实践

### 建议添加类属性的可访问修饰符

**【级别】建议**

**【描述】**

ArkTS提供了private, protected和public可访问修饰符。默认情况下，属性的可访问修饰符为public。选取适当的可访问修饰符可以提升代码的安全性和可读性。注意：如果类中包含private属性，无法通过对象字面量初始化该类。

**【反例】**

```TypeScript
class C1 {
  count: number = 0

  getCount(): number {
    return this.count
  }
}
```

**【正例】**

```TypeScript
class C2 {
  private count: number = 0

  public getCount(): number {
    return this.count
  }
}
```

### 不建议省略浮点数小数点前后的0

**【级别】建议**

**【描述】**

ArkTS中，浮点值包含一个小数点，不要求小数点之前或之后必须有一个数字。在小数点前面和后面都添加数字可以提高代码的可读性。

**【反例】**

```TypeScript
const num1 = .5;
const num2 = 2.;
const num3 = -.7;
```

**【正例】**

```TypeScript
const num4 = 0.5;
const num5 = 2.0;
const num6 = -0.7;
```

### 判断变量是否为Number.NaN时必须使用Number.isNaN()方法

**【级别】要求**

**【描述】**

在ArkTS中，Number.NaN是Number类型的一个特殊值。它被用来表示非数值，这里的数值是指在IEEE浮点数算术标准中定义的双精度64位格式的值。

在ArkTS中，Number.NaN的独特之处在于它不等于任何值，包括其本身。与Number.NaN进行比较时，结果是令人困惑的：Number.NaN !== Number.NaN 和 Number.NaN != Number.NaN 的值都是 true。

因此，必须使用Number.isNaN()函数来测试一个值是否是Number.NaN。

**【反例】**

```TypeScript
if (foo == Number.NaN) {
  // ...
}

if (foo != Number.NaN) {
  // ...
}
```

**【正例】**

```TypeScript
if (Number.isNaN(foo)) {
  // ...
}

if (!Number.isNaN(foo)) {
  // ...
}
```

### 数组遍历优先使用Array对象方法

**【级别】要求**

**【描述】**

对于数组遍历，应该优先使用Array对象方法，如：forEach(), map(), every(), filter(), find(), findIndex(), reduce(), some()。

**【反例】**

```TypeScript
const numbers = [1, 2, 3, 4, 5];
// 依赖已有数组来创建新的数组时，通过for遍历，生成一个新数组
const increasedByOne1: number[] = [];
for (let i = 0; i < numbers.length; i++) {
  increasedByOne1.push(numbers[i] + 1);
}
```

**【正例】**

```TypeScript
const numbers = [1, 2, 3, 4, 5];
// ...
// better: 使用map方法是更好的方式
const increasedByOne2: number[] = numbers.map(num => num + 1);
```

### 不要在控制性条件表达式中执行赋值操作

**【级别】要求**

**【描述】**

控制性条件表达式用于 if、while、for 以及 ?: 等条件判断语句中。

在控制性条件表达式中执行赋值容易导致意外行为，且降低代码的可读性。

**【反例】**

```TypeScript
// 在控制性判断中赋值不易理解
if (isFoo = false) {
  // ...
}
```

**【正例】**

```TypeScript
const isFoo = false; // 在上面赋值，if条件判断中直接使用
if (isFoo) {
  // ...
}
```

### 在finally代码块中，不要使用return、break、continue或抛出异常，避免finally块非正常结束

**【级别】要求**

**【描述】**

在finally代码块中，直接使用return、break、continue、throw语句或调用方法时未处理异常，会导致finally代码块无法正常结束。finally代码块异常结束会影响try或catch代码块中异常的抛出，也可能影响方法的返回值。因此，必须确保finally代码块正常结束。

**【反例】**

```TypeScript
function foo4() {
  try {
    // ...
    return 1;
  } catch (err) {
    // ...
    return 2;
  } finally {
    return 3;
  }
}
```

**【正例】**

```TypeScript
function foo5() {
  try {
    // ...
    return 1;
  } catch (err) {
    // ...
    return 2;
  } finally {
    console.info('XXX!');
  }
}
```

### 避免使用ESObject

**【级别】建议**

**【描述】**

ESObject主要用于ArkTS和TS/JS的跨语言调用场景中的类型标注。在非跨语言调用场景中使用ESObject标注类型，会引入不必要的跨语言调用，导致额外的性能开销。

**【反例】**

```TypeScript
// lib.ets
export interface I {
  sum: number
}

export function getObject1(value: number): I {
  let obj: I = { sum: value };
  return obj
}
```

```TypeScript
// Index.ets
import { getObject1 } from './lib';
// ...
let obj1: ESObject = getObject1(123);
```

**【正例】**

```TypeScript
// lib.ets
export interface I {
  sum: number
}

// ...
export function getObject2(value: number): I {
  let obj: I = { sum: value };
  return obj
}
```

```TypeScript
// Index.ets
import { getObject2, I } from './lib';
// ...
let obj2: I = getObject2(123);
```

### 使用T[]表示数组类型

**【级别】建议**

**【描述】**

ArkTS提供了两种数组类型的表示方式：T[]和Array<T>。建议所有数组类型均使用T[]表示，以提高代码可读性。

**【反例】**

```TypeScript
let x: Array<number> = [1, 2, 3];
let y: Array<string> = ['a', 'b', 'c'];
```

**【正例】**

```TypeScript
// 统一使用T[]语法
let x: number[] = [1, 2, 3];
let y: string[] = ['a', 'b', 'c'];
```