ArkTS 编码风格指南：书写干净、易读且高效的代码

介绍

随着应用开发越来越复杂且跨平台，编写高质量、易维护的代码至关重要。ArkTS作为HarmonyOS生态中的编程语言，提供了强大的特性，但也需要保持一致、严谨的编码规范。本文提供了一系列结构化的推荐，以改善代码的可读性、性能以及可维护性，并突出最佳实践和常见错误。

目的和范围

ArkTS 编码风格指南在业界标准（尤其是TypeScript与JavaScript生态）的基础上，新增了一些专门为ArkTS而设计的规则。其目标包括：

• 代码标准化
• 执行效率提升
• 静态分析能力提升
• 在协作环境中提高安全性及代码清晰度

本指南适用于ArkTS生态系统中系统级及应用层开发。

命名规范

🟡 使用清晰且描述性的标识符

避免单字母、缩写或使用非英文术语。始终保持标识符能够清楚表达意图。

let userName = 'JohnDoe';
function sendMessage(message: string) { ... }

🟡 类（Classes）、枚举（Enums）、命名空间（Namespaces）使用大驼峰命名法（UpperCamelCase）

class UserProfile { ... }
enum AccountType { ADMIN, USER }
namespace AuthUtils { ... }

🟡 变量、方法及参数使用小驼峰命名（lowerCamelCase）

let maxRetry = 5;
function handleLogin(userName: string) { ... }

🟡 常量使用全大写字母且单词之间用下划线区分（UPPER_CASE_WITH_UNDERSCORES）

const MAX_USER_COUNT = 10000;

🟡 避免使用负面的布尔名称

应采用正面的表达方式，并使用is、has、can等明确前缀。

let isEnabled = true;

格式化规则

🟡 使用两个空格缩进

统一使用两空格缩进方式，以提升跨设备及编辑器的可读性。

🟡 单行长度最多120个字符

保持代码行简洁，必要时通过换行保持长条件句或表达式易读。

🟡 所有条件和循环块均使用大括号

即使是一行代码，也需要添加花括号。

if (isValid) {
  process();
}

🟡 switch语句中的case和default语句应缩进

switch (status) {
  case 0: {
    handleIdle();
    break;
  }
  default:
    break;
}

🟡 表达式换行时，运算符置于行尾

// 正确示例
let result = someCondition &&
             anotherCondition &&
             theThirdCondition;

🟡 每行只声明一个变量

let count = 0;
let isReady = true;

🟡 空格使用准则

• 运算符两侧以及逗号后应使用空格
• 逗号或分号前不加空格
• 方法调用的左括号前不加空格

🟡 字符串统一使用单引号

let message = 'Hello ArkTS';

🟡 超过4个属性的对象字面量使用多行格式

let obj = {
  id: 1,
  name: 'Tom',
  age: 30,
  active: true,
  role: 'admin'
};

🟡 else和catch关键字位于对应闭括号的同一行

if (isActive) {
  start();
} else {
  stop();
}

🟡 左括号 { 应放于同一行末尾

function init() {
  // ...
}

编程实践

🟡 明确使用访问修饰符（private、protected、public）以表达代码意图

class Counter {
  private value: number = 0;
  public increment(): void {
    this.value++;
  }
}

🟡 清晰书写浮点数

let pi = 3.14;
let ratio = 0.75;

🟡 检查NaN值时应使用Number.isNaN()

if (Number.isNaN(value)) { ... }

🟡 首选数组方法而非循环

const doubled = numbers.map(n => n * 2);

🟡 条件表达式中避免赋值操作

将赋值与条件逻辑分开处理。

let isReady = checkStatus();
if (isReady) { ... }

🟡 在finally块中禁止使用return、throw、break或continue

这些操作可能会压制关键的错误或重写原始返回值。

try {
  return fetchData();
} catch (err) {
  handleError(err);
} finally {
  log('Completed');
}

🟡 避免使用ESObject类型

尽可能使用明确的接口和本地数据类型避免跨语言带来的性能额外开销。

let obj: I = getObject(123);

🟡 数组类型声明优先使用T[]，而非Array<T>

let names: string[] = ['Alice', 'Bob'];

结语

在HarmonyOS生态中，开发者遵循ArkTS编码风格指南至关重要，有助于团队减少Bug、提升协作效率及代码质量的长期维护。通过清晰且有意图地编写代码，你不仅仅是在写代码，更是在以ArkTS塑造跨平台应用程序的未来。