---

name: coding-standards description: 跨项目基础编码规范，涵盖命名、可读性、不可变性和代码质量审查。框架特定模式请使用详细的前端或后端技能。 origin: ECC

编码标准与最佳实践

适用于所有项目的基础编码规范。

此技能是共享基准，而非详细的框架手册。

• 使用 frontend-patterns 处理 React、状态、表单、渲染和 UI 架构。
• 使用 backend-patterns 或 api-design 处理仓储/服务层、端点设计、验证和服务器特定问题。
• 当你需要最简短的可复用规则层而非完整技能演练时，使用 rules/common/coding-style.md。

何时激活

• 启动新项目或模块
• 审查代码质量和可维护性
• 重构现有代码以遵循规范
• 强制执行命名、格式或结构一致性
• 设置 linting、格式化或类型检查规则
• 向新贡献者介绍编码规范

范围边界

在以下情况激活此技能：

• 描述性命名
• 不可变性默认值
• 可读性、KISS、DRY 和 YAGNI 执行
• 错误处理预期和代码异味审查

不要将此技能作为以下内容的主要来源：

• React 组合、hooks 或渲染模式
• 后端架构、API 设计或数据库分层
• 当已存在更窄的 ECC 技能时的领域特定框架指导

代码质量原则

1. 可读性优先

• 代码被阅读的次数多于编写
• 清晰的变量和函数名
• 自文档化代码优于注释
• 一致的格式

2. KISS（保持简单）

• 能工作的最简单方案
• 避免过度工程
• 不要过早优化
• 易于理解 > 巧妙代码

3. DRY（不要重复自己）

• 将通用逻辑提取为函数
• 创建可复用组件
• 跨模块共享工具函数
• 避免复制粘贴编程

4. YAGNI（你不会需要它）

• 不要在需要之前构建功能
• 避免投机性泛化
• 仅在需要时增加复杂性
• 从简单开始，需要时重构

TypeScript/JavaScript 标准

变量命名

// PASS: GOOD: Descriptive names
const marketSearchQuery = 'election'
const isUserAuthenticated = true
const totalRevenue = 1000

// FAIL: BAD: Unclear names
const q = 'election'
const flag = true
const x = 1000

函数命名

// PASS: GOOD: Verb-noun pattern
async function fetchMarketData(marketId: string) { }
function calculateSimilarity(a: number[], b: number[]) { }
function isValidEmail(email: string): boolean { }

// FAIL: BAD: Unclear or noun-only
async function market(id: string) { }
function similarity(a, b) { }
function email(e) { }

不可变性模式（关键）

// PASS: ALWAYS use spread operator
const updatedUser = {
  ...user,
  name: 'New Name'
}

const updatedArray = [...items, newItem]

// FAIL: NEVER mutate directly
user.name = 'New Name'  // BAD
items.push(newItem)     // BAD

错误处理

// PASS: GOOD: Comprehensive error handling
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')
  }
}

// FAIL: BAD: No error handling
async function fetchData(url) {
  const response = await fetch(url)
  return response.json()
}

Async/Await 最佳实践

// PASS: GOOD: Parallel execution when possible
const [users, markets, stats] = await Promise.all([
  fetchUsers(),
  fetchMarkets(),
  fetchStats()
])

// FAIL: BAD: Sequential when unnecessary
const users = await fetchUsers()
const markets = await fetchMarkets()
const stats = await fetchStats()

类型安全

// PASS: GOOD: Proper types
interface Market {
  id: string
  name: string
  status: 'active' | 'resolved' | 'closed'
  created_at: Date
}

function getMarket(id: string): Promise<Market> {
  // Implementation
}

// FAIL: BAD: Using 'any'
function getMarket(id: any): Promise<any> {
  // Implementation
}

React 最佳实践

组件结构

// PASS: GOOD: Functional component with types
interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function Button({
  children,
  onClick,
  disabled = false,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      className={\`btn btn-\${variant}\`}
    >
      {children}
    </button>
  )
}

// FAIL: BAD: No types, unclear structure
export function Button(props) {
  return <button onClick={props.onClick}>{props.childr