ArkTS编程规范

---

目标和适用范围

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

本文适用于开发者进行系统开发或者应用开发时，使用ArkTS编写代码的场景。

规则来源

ArkTS在保持TypeScript基本语法风格的基础上，进一步强化静态检查和分析。本文部分规则筛选自《OpenHarmony应用TS&JS编程指南》，为ArkTS语言新增的语法添加了规则，旨在提高代码可读性、执行性能。

章节概览

代码风格

包含命名和格式。

编程实践

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

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

术语和定义

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

总体原则

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

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

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

命名

为标识符取一个好名字，提高代码可读性
【描述】

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

• 能清晰的表达意图，避免使用单个字母、未成惯例的缩写来命名
• 使用正确的英文单词并符合英文语法，不要使用中文拼音
• 能区分出意思，避免造成误导

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

【级别】建议

【描述】

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

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

【正例】

// 类名
class User {
  username: string

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

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

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

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

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

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

【级别】建议

【描述】

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

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

变量的名字通常是名词或名词短语，应采用小驼峰命名，以便于理解其含义。

【正例】

let msg = 'Hello world';

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

let userName = 'Zhangsan';

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

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

【级别】建议

【描述】

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

【正例】

const MAX_USER_SIZE = 10000;

enum UserType {
  TEACHER = 0,
  STUDENT = 1
};

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

【级别】建议

【描述】

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

【反例】

let isNoError = true;
let isNotFound = false;

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

【正例】

let isError = false;
let isFound = true;

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

格式

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

【级别】建议

【描述】

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

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

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

【正例】

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等语句的执行体加大括号{}是一种最佳实践，因为省略大括号容易导致错误，并且降低代码的清晰度。

【反例】

if (condition)
  console.log('success');

for (let idx = 0; idx < 5; ++idx)
  console.log(idx);

【正例】

if (condition) {
  console.log('success');
}

for (let idx = 0; idx < 5; ++idx) {
  console.log(idx);
}

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

【级别】建议

【描述】

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

【正例】

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

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

【级别】建议

【描述】

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

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

【正例】

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

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

【级别】要求

【描述】

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

这种方式更易添加变量声明，不用考虑将;变成,，以免引入错误。另外，每个语句只声明一个变量，用debugger逐个调试也很方便，而不是一次跳过所有变量。

【反例】

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

【正例】

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

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

【级别】建议

【描述】

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

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

【反例】

// if 和左括号 ( 之间没有加空格
if(isJedi) {
  fight();
}

// 函数名fight和左括号 ( 之间加了空格
function fight (): void {
  console.log('Swooosh!');
}

【正例】

// if 和左括号之间加一个空格
if (isJedi) {
  fight();
}

// 函数名fight和左括号 ( 之间不加空格
function fight(): void {
  console.log('Swooosh!');
}

【反例】

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

【正例】

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

【正例】

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

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

【正例】

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

建议字符串使用单引号

【级别】建议

【描述】

较为约定俗成，单引号优于双引号。

【反例】

let message = "world";
console.log(message);

【正例】

let message = 'world';
console.log(message);

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

【级别】建议

【描述】

对象字面量要么每个属性都换行，要么所有属性都在同一行。当对象字面量属性超过4个的时候，建议统一换行。

【反例】

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

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

【正例】

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

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

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

【级别】建议

【描述】

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

【反例】

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

【正例】

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

【反例】

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

【正例】

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

大括号{和语句在同一行

【级别】建议

【描述】

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

【反例】

function foo()
{
  //...
}

【正例】

function foo() {
  //...
}

编程实践

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

【级别】建议

【描述】

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

【反例】

class C {
  count: number = 0

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

【正例】

class C {
  private count: number = 0

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

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

【级别】建议

【描述】

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

【反例】

const num = .5;
const num = 2.;
const num = -.7;

【正例】

const num = 0.5;
const num = 2.0;
const num = -0.7;

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

【级别】要求

【描述】

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

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

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

【反例】

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

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

【正例】

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

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

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

【级别】要求

【描述】

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

【反例】

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

【正例】

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

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

【级别】要求

【描述】

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

在控制性条件表达式中执行赋值，常常导致意料之外的行为，且代码的可读性非常差。

【反例】

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

【正例】

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

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

【级别】要求

【描述】

在finally代码块中，直接使用return、break、continue、throw语句，或由于调用方法的异常未处理，会导致finally代码块无法正常结束。非正常结束的finally代码块会影响try或catch代码块中异常的抛出，也可能会影响方法的返回值。所以要保证finally代码块正常结束。

【反例】

function foo() {
  try {
    ...
    return 1;
  } catch (err) {
    ...
    return 2;
  } finally {
    return 3;
 }
}

【正例】

function foo() {
  try {
    ...
    return 1;
  } catch (err) {
    ...
    return 2;
  } finally {
    console.log('XXX!');
  }
}

避免使用ESObject

【级别】建议

【描述】

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

【反例】

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

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

// app.ets
import { getObject } from 'lib'
let obj: ESObject = getObject(123);

【正例】

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

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

// app.ets
import { getObject, I } from 'lib'
let obj: I = getObject(123);

使用T[]表示数组类型

【级别】建议

【描述】

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

【反例】

let x: Array = [1, 2, 3];
let y: Array = ['a', 'b', 'c'];

【正例】

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

---