一、目标和适用范围
本文参考业界标准及实践，结合 ArkTS 语言特点，为提高代码的规范、安全、性能提供编码指南。适用于开发者进行系统开发或者应用开发时，使用 ArkTS 编写代码的场景。
二、规则来源
ArkTS 在保持 TypeScript 基本语法风格的基础上，进一步强化静态检查和分析。部分规则筛选自《OpenHarmony 应用 TS&JS 编程指南》，并为 ArkTS 语言新增的语法添加了规则，旨在提高代码可读性、执行性能。
三、总体原则
规则分为两个级别：
（一）要求
表示原则上应该遵从。本文所有内容目前均为针对 ArkTS 的要求。
（二）建议
表示该条款属于最佳实践，可结合实际情况考虑是否纳入。
四、命名规范
（一）基本原则
为标识符取一个好名字，提高代码可读性。好的标识符命名应遵循以下原则：
- 能清晰表达意图，避免使用单个字母、未成惯例的缩写来命名。
- 使用正确的英文单词并符合英文语法，不要使用中文拼音。
- 能区分出意思，避免造成误导。
（二）具体命名风格
- 类名、枚举名、命名空间名：采用 UpperCamelCase 风格（首字母大写的驼峰命名法），通常是名词或名词短语，不应使用动词，避免类似 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 风格（小驼峰命名），函数命名通常是动词或动词短语，变量名字通常是名词或名词短语。
- 正例：
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 等，避免使用否定的布尔变量名。
- 反例：
let isNoError = true;
let isNotFound = false;
function empty() {}
function next() {}- 正例：let isError = false;
let isFound = true;
function isEmpty() {}
function hasNext() {}五、格式规范
（一）缩进
使用空格缩进，禁止使用 tab 字符。建议大部分场景优先使用 2 个空格，换行导致的缩进优先使用 4 个空格，应在代码编辑器中配置使用空格进行缩进。
（二）行宽
行宽不超过 120 个字符，除非超过 120 能显著增加可读性且不会隐藏信息。例外情况：包含超过 120 个字符的命令或 URL 的注释、预处理的 error 信息可保持一行。
（三）大括号
- 条件语句和循环语句（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 需缩进一层（2 个空格），开关标签之后换行的语句需再缩进一层（2 个空格）。
- 正例：
switch (condition) {
case 0: {
doSomething();
break;
}
case 1: {
doOtherthing();
break;
}
default:
break;
}（四）表达式换行
表达式换行需保持一致性，运算符放行末。
（五）变量定义和赋值
多个变量定义和赋值语句不允许写在一行，每个语句应只声明一个变量。 - 反例：
let maxCount = 10,
isCompleted = false;
let pointX, pointY;
pointX = 10;
pointY = 0;- 正例：let maxCount = 10;
let isCompleted = false;
let pointX = 0;
let pointY = 0;（六）空格使用
- if, for, while, switch 等关键字与左括号(之间加空格。
- 函数定义和调用时，函数名称与参数列表的左括号(之间不加空格。
- 关键字 else 或 catch 与其之前的大括号}之间加空格。
- 任何打开大括号({)之前加空格（两个例外：作为函数的第一个参数或数组中的第一个元素时，对象之前不用加空格；在模板中不用加空格）。
- 二元操作符(+ - \* = < > <= >= =! && ||)前后加空格，三元操作符(? :)符号两侧均加空格。
- 数组初始化中的逗号和函数中多个参数之间的逗号后加空格，逗号(,)或分号(;)之前不加空格，数组的中括号([])内侧不要加空格，不要出现多个连续空格。
（七）字符串引号
建议字符串使用单引号。 - 反例：
let message = "world";
console.log(message);- 正例：let message = "world";
console.log(message);（八）对象字面量属性
对象字面量属性超过 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 位置
把 else/catch 放在 if/try 代码块关闭括号的同一行。 - 反例：
if (isOk) {
doThing1();
doThing2();
} else {
doThing3();
}
try {
doSomething();
} catch (err) {
// 处理错误
}- 正例：if (isOk) {
doThing1();
doThing2();
} else {
doThing3();
}
try {
doSomething();
} catch (err) {
// 处理错误
}（十）大括号位置
大括号{和语句在同一行。 - 反例：
function foo() {
//...
}- 正例：function foo() {
//...
}六、编程实践规范
（一）类属性可访问修饰符
建议添加类属性的可访问修饰符（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，以提高代码可读性。 - 反例：
const num = 0.5;
const num = 2;
const num = -0.7;- 正例：const num = 0.5;
const num = 2.0;
const num = -0.7;（三）判断 Number.NaN
判断变量是否为 Number.NaN 时必须使用 Number.isNaN()方法。 - 反例：
if (foo == Number.NaN) {
//...
}
if (foo != Number.NaN) {
//...
}- 正例：if (Number.isNaN(foo)) {
//...
}
if (!Number.isNaN(foo)) {
//...
}（四）数组遍历
数组遍历优先使用 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 (isFoo = false) {
...
}- 正例：const isFoo = someBoolean; // 在上面赋值，if条件判断中直接使用
if (isFoo) {
...
}（六）finally 代码块
在 finally 代码块中，不要使用 return、break、continue 或抛出异常，避免 finally 块非正常结束，影响 try 或 catch 代码块中异常的抛出和方法的返回值。 - 反例：
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，在非跨语言调用场景中使用 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[]表示数组类型，以提高代码可读性。 - 反例：
let x: Array<number> = [1, 2, 3];
let y: Array<string> = ["a", "b", "c"];- 正例：// 统一使用T[]语法
let x: number[] = [1, 2, 3];
let y: string[] = ["a", "b", "c"];