coding-standards

# 程式碼標準與最佳實務 適用於所有專案的通用程式碼標準。 ## 程式碼品質原則 ### 1. 可讀性優先 - 程式碼被閱讀的次數遠多於被撰寫的次數 - 使用清晰的變數和函式名稱 - 優先使用自文件化的程式碼而非註解 - 保持一致的格式化 ### 2. KISS（保持簡單） - 使用最簡單的解決方案 - 避免過度工程 - 不做過早優化 - 易於理解 > 聰明的程式碼 ### 3. DRY（不重複自己） - 將共用邏輯提取為函式 - 建立可重用的元件 - 在模組間共享工具函式 - 避免複製貼上程式設計 ### 4. YAGNI（你不會需要它） - 在需要之前不要建置功能 - 避免推測性的通用化 - 只在需要時增加複雜度 - 從簡單開始，需要時再重構 ## TypeScript/JavaScript 標準 ### 變數命名 ```typescript // PASS: 良好：描述性名稱 const marketSearchQuery = 'election' const isUserAuthenticated = true const totalRevenue = 1000 // FAIL: 不良：不清楚的名稱 const q = 'election' const flag = true const x = 1000 ``` ### 函式命名 ```typescript // PASS: 良好：動詞-名詞模式 async function fetchMarketData(marketId: string) { } function calculateSimilarity(a: number[], b: number[]) { } function isValidEmail(email: string): boolean { } // FAIL: 不良：不清楚或只有名詞 async function market(id: string) { } function similarity(a, b) { } function email(e) { } ``` ### 不可���性模式（關鍵） ```typescript // PASS: 總是使用展開運算符 const updatedUser = { ...user, name: 'New Name' } const updatedArray = [...items, newItem] // FAIL: 永遠不要直接修改 user.name = 'New Name' // 不良 items.push(newItem) // 不良 ``` ### 錯誤處理 ```typescript // PASS: 良好：完整的錯誤處理 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 fetc...