HarmonyOS / ArkTS Coding Style

This file extends common/coding-style.md with HarmonyOS and ArkTS-specific content.

ArkTS Language Constraints

ArkTS is a strict, statically-typed subset of TypeScript. Violating these constraints causes compilation failures.

Type System

• No any or unknown types - always use explicit types
• No index access types - use type names directly
• No conditional type aliases or infer keyword
• No intersection types - use inheritance
• No mapped types - use classes and regular idioms
• No typeof for type annotations - use explicit type declarations
• No as const assertions - use explicit type annotations
• No structural typing - use inheritance, interfaces, or type aliases
• No TypeScript utility types except Partial, Required, Readonly, Record
• For Record<K, V>, index expression type is V | undefined
• Omit type annotations in catch clauses (ArkTS does not support any/unknown)

Functions & Classes

• No function expressions - use arrow functions
• No nested functions - use lambdas
• No generator functions - use async/await for multitasking
• No Function.apply, Function.call, Function.bind - follow traditional OOP for this
• No constructor type expressions - use lambdas
• No constructor signatures in interfaces or object types - use methods or classes
• No declaring class fields in constructors - declare in class body
• No this in standalone functions or static methods - only in instance methods
• No new.target
• No definite assignment assertions (let v!: T) - use initialized declarations
• No class literals - introduce named class types
• No using classes as objects (assigning to variables) - class declarations introduce types, not values
• Only one static block per class - merge all static statements

Object & Property Access

• No dynamic field declaration or obj["field"] access - use obj.field syntax
• No delete operator - use nullable type with null to mark absence
• No prototype assignment - use classes and interfaces
• No in operator - use instanceof
• No reassigning object methods - use wrapper functions or inheritance
• No Symbol() API (except Symbol.iterator)
• No globalThis or global scope - use explicit module exports/imports
• No namespaces as objects - use classes or modules
• No statements inside namespaces - use functions

Destructuring & Spread

• No destructuring assignments or variable declarations - use intermediate objects and field-by-field access
• No destructuring parameter declarations - pass parameters directly, assign local names manually
• Spread operator only for expanding arrays (or array-derived classes) into rest parameters or array literals

Modules & Imports

• No require() - use regular import syntax
• No export = ... - use normal export/import
• No import assertions - imports are compile-time in ArkTS
• No UMD modules
• No wildcards in module names
• All import statements must appear before all other statements
• TypeScript codebases must not depend on ArkTS codebases via import (reverse is supported)

Other Restrictions

• No var - use let
• No for...in loops - use regular for loops for arrays
• No with statements
• No JSX expressions
• No # private identifiers - use private keyword
• No declaration merging (classes, interfaces, enums) - keep definitions compact
• No index signatures - use arrays
• Comma operator only in for loops
• Unary operators +, -, ~ only for numeric types (no implicit string conversion)
• Enum members: only same-type compile-time expressions for explicit initializers
• Function return type inference is limited - specify return types explicitly when calling functions with omitted return types

Object Literals

• Supported only when compiler can infer the corresponding class or interface
• NOT supported for: any/Object/object types, classes/interfaces with methods, classes with parameterized constructors, classes with readonly fields

Naming Conventions

• Variables / functions: camelCase (e.g., getUserInfo, goodsList)
• Classes / interfaces: PascalCase (e.g., UserViewModel, IGoodsModel)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_PAGE_SIZE, COLOR_PRIMARY)
• File names: PascalCase for components (e.g., HomePage.ets), camelCase for utilities

Formatting

• Prefer double quotes for strings
• Semicolons at end of statements
• Never use var - prefer const, then let
• All methods, parameters, return values must have complete type annotations

File Organization

• Component files (.ets): one @ComponentV2 per file
• ViewModel files: one ViewModel class per file
• Model files: related data models may share a file
• Keep files under 400 lines; extract helpers for files approaching 800 lines

Comments

• File header: @file (file purpose) + @author (developer), if the project already uses file headers
• Public methods: JSDoc with @param, @returns; add @example for complex methods
• Match the project's existing documentation language; use English unless the repository has already standardized on Chinese comments

Error Handling

// Use try/catch with proper error handling
try {
  const result = await riskyOperation()
  return result
} catch (error) {
  hilog.error(0x0000, 'TAG', 'Operation failed: %{public}s', error)
  throw new Error('User-friendly error message')
}

Immutability

Follow the common immutability principles - create new objects instead of mutating:

// BAD: mutation
function updateUser(user: UserModel, name: string): UserModel {
  user.name = name  // direct mutation
  return user
}

// GOOD: immutable - create new instance
function updateUser(user: UserModel, name: string): UserModel {
  const updated = new UserModel()
  updated.id = user.id
  updated.name = name
  updated.email = user.email
  return updated
}