📏 Coding Standards — 编码规范指南

# 编码标准与最佳实践 面向可维护、可扩展 TypeScript/JavaScript 代码的通用标准。 ## 快速开始 1. 可读性优先 —— 清晰的命名，自解释代码 2. 类型安全 —— 避免 any，使用显式接口 3. 错误处理 —— try-catch 并指定错误类型 4. 不可变性 —— 使用展开运算符，禁止直接修改 5. 测试结构 —— AAA 模式（Arrange, Act, Assert） ## 核心原则 KISS —— 选择最简单且可行的方案，不提前优化。 DRY —— 将公共逻辑抽取为可复用的函数与组件。 YAGNI —— 不需要时不构建。先保持简单，需要时再重构。 可读性 —— 代码被阅读的次数是编写的 10 倍，清晰优于炫技。 ## 命名标准 ### 变量 ``typescript // Good: Descriptive, type-hinted by name const marketSearchQuery = 'election' const isUserAuthenticated = true const totalRevenue = 1000 // Bad: Single-letter, unclear const q = 'election' const flag = true const x = 1000 ` ### 函数 `typescript // Good: Verb-noun pattern async function fetchMarketData(id: string) { } function calculateSimilarity(a: number[], b: number[]) { } function isValidEmail(email: string): boolean { } // Bad: Unclear or noun-only async function market(id: string) { } function similarity(a, b) { } function email(e) { } ` ## 参考资料 - references/typescript.md —— type safety, immutability, async patterns - references/react.md —— component structure, hooks, state management - references/api-design.md —— REST conventions, validation, error responses - references/file-org.md —— project structure, file naming - references/testing.md —— test patterns, AAA structure, test naming - references/code-smells.md` —— anti-patterns, long functions, deep nesting, magic numbers --- Adapted from everything-claude-code by @affaan-m (MIT)