1k-code-quality

# Code Quality

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

## Lint Commands

```bash
# Pre-commit (fast, only staged files)
yarn lint:staged
yarn tsc:staged

# CI only (full project check)
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`.

## Pre-Commit Workflow

For fast pre-commit validation:
```bash
# Lint only modified files (recommended)
yarn lint:staged

# Or with type check
yarn lint:staged && yarn tsc:staged
```

## 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)
```

## 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> {
  // ...
}
```

## 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;
```

## 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');
}
```

### 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());
```

## Detailed Guides

### Code Quality Standards
See [code-quality.md](references/rules/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

### Fixing Lint Warnings
See [fix-lint.md](references/rules/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

## Spellcheck

If a technical term triggers spellcheck errors:
```bash
# Check if word exists
grep -i "yourword" development/spellCheckerSkipWords.txt

# Add if not present (ask team lead first)
echo "yourword" >> development/spellCheckerSkipWords.txt
```

## Checklist

### Pre-commit
- [ ] `yarn lint:staged` passes
- [ ] `yarn tsc:staged` passes

### Code Quality
- [ ] All comments are in English
- [ ] No commented-out code committed
- [ ] Functions have single responsibility
- [ ] No unnecessary abstractions
- [ ] Consistent naming conventions

## Related Skills

- `/1k-sentry-analysis` - Sentry error analysis and fixes
- `/1k-test-version` - Test version creation workflow
- `/1k-coding-patterns` - General coding patterns