华为官方文档及OpenHarmony社区实践整理，涵盖ArkTS/TS代码风格、命名、注释、工程化检查等核心内容
一、通用原则
代码清晰优先：直白简单的逻辑比注释更有效。不要为了快速开发牺牲健壮性和可读性。
工具自动化：使用IDE自带格式化（
Ctrl+Alt+L），保持空格、换行一致。消灭魔鬼数字/字符串：所有业务含义的值（如状态码、银行代码）必须定义为常量：
typescript
// 不规范 if (transactionStatus == 1) { showMessage("交易成功"); } // 规范 const TRANSACTION_SUCCESS = 1; if (transactionStatus == TRANSACTION_SUCCESS) { showMessage("交易成功"); }复用原则：代码复制三次以上，必须抽取为公共函数或组件。
分号规范：除
build()函数外，所有语句必须以分号;结束。
二、命名规范
| 类型 | 风格 | 示例 | 要求 |
|---|---|---|---|
| 类/接口/枚举/命名空间 | 大驼峰 (UpperCamelCase) | BankAccountManager、UserType、Base64Utils | 类名是名词，避免Data、Info等模糊词；接口可用形容词+able |
| 变量/方法/参数 | 小驼峰 (lowerCamelCase) | userName、calculateInterest()、isTransactionValid() | 方法名用动词/动词短语；布尔方法用is/has/can前缀 |
| 常量/枚举值 | 全大写下划线 (CONSTANT_CASE) | MAX_TRANSACTION_AMOUNT | 表达完整语义 |
| 文件命名 | .ets/.ts：大驼峰.js：小驼峰 | Index.ets、EntryAbility.ets、index.js | 资源文件可用小驼峰或snake_case |
关键禁忌：避免拼音、无意义缩写（如acc→account）；禁止使用系统关键字（如onClick、padding）作为变量名；避免否定布尔变量（如isNoError→isError）。
三、格式规范
缩进：只用空格，推荐2个空格缩进，禁用Tab键。
行宽：不超过120个字符。
大括号：
if、for、while等语句即使只有一行也必须使用大括号。typescript
// 不规范 if (condition) console.log('success'); // 规范 if (condition) { console.log('success'); }空格规则：
关键字（
if/for）与括号间加空格；函数名与括号间不加空格。二元操作符前后加空格；逗号后加空格。
else与前面}之间加空格。
变量声明：每行只声明一个变量，禁止
let a=1, b=2;。
四、注释规范
好代码自解释：不言自明的方法/变量不需要注释，不要翻译命名。
复杂逻辑必加：说明"为什么"而非"是什么"（如复利计算的特殊公式）。
JSDoc/ArkTSDoc：使用
/** */格式为类、函数、参数添加说明，配合IDE生成智能提示。typescript
/** * 计算理财产品利息（复利方式，节假日不计息） * @param principal 本金 * @param dailyRate 日利率 * @returns 总利息 */ function calculateInterest(principal: number, dailyRate: number): number { ... }
五、代码结构限制
| 指标 | 限制 | 处理方式 |
|---|---|---|
| 函数行数 | ≤80行 | 超过则拆分多个子函数 |
| 嵌套深度 | ≤4层 | 使用提前返回（Guard Clauses）减少嵌套 |
| 重复代码 | 3行×3次 或 5行×2次 | 必须抽取复用 |
示例：减少嵌套（提前返回）
typescript
// 不规范：5层嵌套 function check(transaction) { if (transaction.isValid) { if (transaction.amount > 0) { if (transaction.targetAccount?.isActive) { return true; } } } return false; } // 规范：提前返回 function check(transaction) { if (!transaction.isValid) return false; if (transaction.amount <= 0) return false; if (!transaction.targetAccount?.isActive) return false; return true; }六、Lint工具落地
"没有Lint的规范只是建议，有了Lint的规范才是规则。"
在项目中配置ESLint自动检查，核心配置项包括：
javascript
// .eslintrc.arkts.js 核心规则示例 module.exports = { parser: '@typescript-eslint/parser', extends: ['@typescript-eslint/recommended'], rules: { 'indent': ['error', 2], // 2空格缩进 'semi': ['error', 'always'], // 必须分号 'max-len': ['warn', { code: 120 }], // 行宽120 'max-depth': ['warn', { max: 4 }], // 嵌套≤4层 'complexity': ['warn', { max: 15 }], // 圈复杂度≤15 '@typescript-eslint/no-explicit-any': 'error', // 禁用any '@typescript-eslint/prefer-optional-chain': 'error', // 使用可选链 }, };具体配置可参考
@hw-stylistic规则集，以及@typescript-eslint推荐配置。
七、异常处理规范
| 场景 | 规范 | 示例 |
|---|---|---|
| API参考示例 | 不加异常处理，保持简洁 | 直接调用API，不添加.catch()或try-catch |
| 开发指南/实际应用 | 必须加异常处理 | 使用try-catch捕获同步异常，.catch()捕获Promise异常，并导入BusinessError获取错误码 |
开发指南示例：
typescript
import { BusinessError } from '@kit.BasicServicesKit'; // 异步场景 doSthAsync().catch((err: BusinessError) => { console.error(`Failed. Code: ${err.code}, message: ${err.message}`); }); // 同步场景 try { doSthSync(); } catch (error) { const err: BusinessError = error as BusinessError; console.error(`Failed. Code: ${err.code}`); }八、补充要点
UI组件属性：宽高、字号等数字属性不加单位（vp/fp/px），系统自动处理：
.width(100)而非.width('100vp')。导入别名：依赖包的别名应与包名空间一致，避免自定义缩写。
参考来源：官方完整规范见[OpenHarmony ArkTS编程规范]、[示例代码风格指南]以及[各语言编程规范]。