1k-code-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality

代码质量

Linting, documentation, and general code quality standards for OneKey.

OneKey的代码检查、文档及通用代码质量标准。

Lint Commands

代码检查命令

bash

undefined

bash

undefined

Pre-commit (fast, only staged files)

提交前检查（快速，仅检查暂存文件）

yarn lint:staged yarn tsc:staged

CI only (full project check)

仅CI环境使用（全项目检查）

yarn lint # Comprehensive: TypeScript, ESLint, folder structure, i18n yarn lint:only # Quick: oxlint only yarn tsc:only # Full type check


**Note:** `yarn lint` is for CI only. For pre-commit, always use `yarn lint:staged`.

yarn lint # 全面检查：TypeScript、ESLint、目录结构、国际化 yarn lint:only # 快速检查：仅oxlint yarn tsc:only # 完整类型检查


**注意：** `yarn lint`仅用于CI环境。提交前请始终使用`yarn lint:staged`。

Pre-Commit Workflow

提交前工作流

For fast pre-commit validation:

bash

undefined

用于快速提交前验证：

bash

undefined

Lint only modified files (recommended)

仅检查修改的文件（推荐）

yarn lint:staged

Or with type check

或包含类型检查

yarn lint:staged && yarn tsc:staged

undefined

yarn lint:staged && yarn tsc:staged

undefined

Common Lint Fixes

常见代码检查修复方案

typescript

// Unused variable - prefix with underscore
const { used, unused } = obj;     // ❌ Error: 'unused' is defined but never used
const { used, unused: _unused } = obj;  // ✅ OK

// Unused parameter - prefix with underscore
function foo(used: string, unused: number) {}     // ❌ Error
function foo(used: string, _unused: number) {}    // ✅ OK

// Floating promise - add void or await
someAsyncFunction();        // ❌ Error: Promises must be awaited
void someAsyncFunction();   // ✅ OK (fire-and-forget)
await someAsyncFunction();  // ✅ OK (wait for result)

typescript

// 未使用变量 - 以下划线为前缀
const { used, unused } = obj;     // ❌ 错误：'unused'已定义但未使用
const { used, unused: _unused } = obj;  // ✅ 正确

// 未使用参数 - 以下划线为前缀
function foo(used: string, unused: number) {}     // ❌ 错误
function foo(used: string, _unused: number) {}    // ✅ 正确

// 浮动Promise - 添加void或await
someAsyncFunction();        // ❌ 错误：Promise必须被await
void someAsyncFunction();   // ✅ 正确（无需等待结果）
await someAsyncFunction();  // ✅ 正确（等待结果返回）

Language Requirements

语言要求

All comments must be written in English:

typescript

// ✅ GOOD: English comment
// Calculate the total balance including pending transactions

// ❌ BAD: Chinese comment
// 计算总余额，包括待处理的交易

// ✅ GOOD: JSDoc in English
/**
 * Fetches user balance from the blockchain.
 * @param address - The wallet address to query
 * @returns The balance in native token units
 */
async function fetchBalance(address: string): Promise<bigint> {
  // ...
}

所有注释必须使用英文：

typescript

// ✅ 规范：英文注释
// Calculate the total balance including pending transactions

// ❌ 不规范：中文注释
// 计算总余额，包括待处理的交易

// ✅ 规范：英文JSDoc
/**
 * Fetches user balance from the blockchain.
 * @param address - The wallet address to query
 * @returns The balance in native token units
 */
async function fetchBalance(address: string): Promise<bigint> {
  // ...
}

When to Comment

注释场景

typescript

// ✅ GOOD: Explain non-obvious logic
// Use 1.5x gas limit to account for estimation variance on this chain
const gasLimit = estimatedGas * 1.5n;

// ✅ GOOD: Explain business logic
// Premium users get 50% discount on transaction fees
const fee = isPremium ? baseFee * 0.5 : baseFee;

// ❌ BAD: Obvious comment
// Set the value to 5
const value = 5;

typescript

// ✅ 规范：解释非直观逻辑
// Use 1.5x gas limit to account for estimation variance on this chain
const gasLimit = estimatedGas * 1.5n;

// ✅ 规范：解释业务逻辑
// Premium users get 50% discount on transaction fees
const fee = isPremium ? baseFee * 0.5 : baseFee;

// ❌ 不规范：冗余注释
// Set the value to 5
const value = 5;

Development Principles

开发原则

Single Responsibility

单一职责

Each function should perform a single, atomic task:

typescript

// ✅ GOOD: Single responsibility
async function fetchUserBalance(userId: string): Promise<Balance> {
  const user = await getUser(userId);
  return await getBalanceForAddress(user.address);
}

// ❌ BAD: Multiple responsibilities
async function fetchUserBalanceAndUpdateUI(userId: string) {
  const user = await getUser(userId);
  const balance = await getBalanceForAddress(user.address);
  setBalanceState(balance);
  showNotification('Balance updated');
  logAnalytics('balance_fetched');
}

每个函数应执行单一、独立的任务：

typescript

// ✅ 规范：单一职责
async function fetchUserBalance(userId: string): Promise<Balance> {
  const user = await getUser(userId);
  return await getBalanceForAddress(user.address);
}

// ❌ 不规范：多职责
async function fetchUserBalanceAndUpdateUI(userId: string) {
  const user = await getUser(userId);
  const balance = await getBalanceForAddress(user.address);
  setBalanceState(balance);
  showNotification('Balance updated');
  logAnalytics('balance_fetched');
}

Avoid Over-Abstraction

避免过度抽象

Don't create helpers for one-time operations:

typescript

// ❌ BAD: Over-abstracted
const createUserFetcher = (config: Config) => {
  return (userId: string) => {
    return fetchWithConfig(config, `/users/${userId}`);
  };
};
const fetchUser = createUserFetcher(defaultConfig);
const user = await fetchUser(userId);

// ✅ GOOD: Simple and direct
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

不要为一次性操作创建辅助工具：

typescript

// ❌ 不规范：过度抽象
const createUserFetcher = (config: Config) => {
  return (userId: string) => {
    return fetchWithConfig(config, `/users/${userId}`);
  };
};
const fetchUser = createUserFetcher(defaultConfig);
const user = await fetchUser(userId);

// ✅ 规范：简洁直接
const user = await fetch(`/api/users/${userId}`).then(r => r.json());

Detailed Guides

详细指南

Code Quality Standards

代码质量标准

See code-quality.md for comprehensive guidelines:

Linting commands and pre-commit workflow
Comment and documentation standards
Language requirements (English only)
Single responsibility principle
Avoiding over-abstraction
Consistent naming conventions
Code quality checklist

查看code-quality.md获取完整指南：

代码检查命令与提交前工作流
注释与文档规范
语言要求（仅英文）
单一职责原则
避免过度抽象
统一命名规范
代码质量检查清单

Fixing Lint Warnings

修复代码检查警告

See fix-lint.md for complete lint fix workflow:

Analyzing lint warnings
Categorizing lint errors
Common fix patterns by category
Spellcheck fixes
Unused variable/parameter handling
Automated fix strategies
Testing after fixes

查看fix-lint.md获取完整的代码检查修复工作流：

分析代码检查警告
分类代码检查错误
按类别划分的常见修复模式
拼写检查修复
未使用变量/参数处理
自动修复策略
修复后测试

Spellcheck

拼写检查

If a technical term triggers spellcheck errors:

bash

undefined

如果技术术语触发拼写检查错误：

bash

undefined

Check if word exists

检查单词是否已存在

grep -i "yourword" development/spellCheckerSkipWords.txt

Add if not present (ask team lead first)

若不存在则添加（需先咨询团队负责人）

echo "yourword" >> development/spellCheckerSkipWords.txt

undefined

echo "yourword" >> development/spellCheckerSkipWords.txt

undefined

1k-code-quality

Original

Translation

Code Quality

代码质量

Lint Commands

代码检查命令

Pre-commit (fast, only staged files)

提交前检查（快速，仅检查暂存文件）

CI only (full project check)

仅CI环境使用（全项目检查）

Pre-Commit Workflow

提交前工作流

Lint only modified files (recommended)

仅检查修改的文件（推荐）

Or with type check

或包含类型检查

Common Lint Fixes

常见代码检查修复方案

Language Requirements

语言要求

When to Comment

注释场景

Development Principles

开发原则

Single Responsibility

单一职责

Avoid Over-Abstraction

避免过度抽象

Detailed Guides

详细指南

Code Quality Standards

代码质量标准

Fixing Lint Warnings

修复代码检查警告

Spellcheck

拼写检查

Check if word exists

检查单词是否已存在

Add if not present (ask team lead first)

若不存在则添加（需先咨询团队负责人）

Checklist

检查清单

Pre-commit

提交前

Code Quality

代码质量

Related Skills

相关技能