coding-standards

# 编码标准与最佳实践（Coding Standards & Best Practices）

适用于所有项目的通用编码标准。

## 代码质量原则（Code Quality Principles）

### 1. 可读性优先（Readability First）
- 代码被阅读的次数远多于编写的次数
- 使用清晰的变量和函数名称
- 优先选择自解释代码，而非过多注释
- 保持一致的格式化风格

### 2. KISS 原则（Keep It Simple, Stupid）
- 采用最简单的可行方案
- 避免过度工程（Over-engineering）
- 拒绝过早优化
- 易于理解胜过奇技淫巧

### 3. DRY 原则（Don't Repeat Yourself）
- 将公共逻辑提取到函数中
- 创建可复用的组件
- 在模块间共享工具函数（Utilities）
- 避免复制粘贴式编程

### 4. YAGNI 原则（You Aren't Gonna Need It）
- 不要在需求出现前构建功能
- 避免投机性的通用化设计
- 仅在必要时增加复杂性
- 从简单开始，在需要时重构

## TypeScript/JavaScript 标准

### 变量命名

```typescript
// ✅ 推荐：描述性名称
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

// ❌ 糟糕：语义不明
const q = 'election'
const flag = true
const x = 1000
```

### 函数命名

```typescript
// ✅ 推荐：动词-名词模式
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// ❌ 糟糕：语义不明或仅有名词
async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }
```

### 不可变模式（Immutability Pattern - 至关重要）

```typescript
// ✅ 始终使用展开运算符（Spread Operator）
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// ❌ 严禁直接修改（Mutate）
user.name = 'New Name'  // 糟糕
items.push(newItem)     // 糟糕
```

### 错误处理（Error Handling）

```typescript
// ✅ 推荐：全面的错误处理
async function fetchData(url: string) {
  try {
    const response = await fetch(url)

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
    }

    return await response.json()
  } catch (error) {
    console.error('Fetch failed:', error)
    throw new Error('Failed to fetch data')
  }
}

// ❌ 糟糕：缺少错误处理
async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}
```

### Async/Await 最佳实践

```typescript
// ✅ 推荐：尽可能并行执行
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// ❌ 糟糕：非必要的串行