code-quality

name	code-quality
description	Code quality standards and best practices. Use when fixing lint warnings, running pre-commit tasks, handling unused variables, writing comments, or ensuring code quality. All comments must be in English. Triggers on lint, linting, eslint, oxlint, tsc, type check, unused variable, comment, documentation, spellcheck, code quality, pre-commit, yarn lint.
allowed-tools	Read, Grep, Glob

Code Quality

Linting, documentation, and general code quality standards.

Lint Commands

# 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:

# Lint only modified files (recommended)
yarn lint:staged

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

Common Lint Fixes

// 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:

// ✅ 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

// ✅ 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:

// ✅ 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:

// ❌ 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 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 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:

# 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

• /sentry-analysis - Sentry error analysis and fixes
• /coding-patterns - General coding patterns