JavaScript 語法靈活寬鬆,若缺乏規範,極易產生難以維護的「義大利麵代碼」。本文整理業界公認的編碼規範,涵蓋檔案組織、排版、命名、宣告、註解等面向,助您撰寫高品質、可長期維護的程式碼。
所有 JavaScript 程式應置於獨立 .js 檔,透過 <script src="filename.js"></script> 引入。避免在 HTML 內嵌腳本,以利快取、壓縮與維護。
<script> 標籤應放在 </body> 之前,避免阻塞頁面渲染。若需在 <head> 載入,請加上 defer 或 async 屬性。
每行不超過 80 字元(現代螢幕可放寬至 100-120)。過長行應換行,下一行縮進 8 空格(或 2 個縮進層級),與區塊縮進(4 空格)區分。
**務必**在每個陳述式結尾加上分號。雖然 ASI(自動分號插入)機制存在,但明確分號可防止壓縮、合併檔案時發生錯誤。
換行應在運算子、逗號**之後**進行,而非變數名、字串、數字或 ) ] ++ -- 之後。
// 推薦
const valueC = valueA +
valueB;
// 不推薦
const valueB = valueA
+ valueC;
**禁止使用 Tab 鍵**,因不同編輯器解析寬度不一。建議設定編輯器將 Tab 轉為 4 空格(VS Code、WebStorm、Sublime、Vim 皆支援)。
//:用於程式碼行說明,置於程式碼上方或行尾,前方保留一空格。/* ... */:用於函式/類別/檔案頂部的正式文件化說明(JSDoc 格式),或暫時註解大段程式碼。// 將 a 設為 0)。// 不好:顯而易見
var valueA = 0; // initialize valueA to be zero
// 好:說明業務意圖
const MAX_RETRY_COUNT = 3; // 依據 API SLA 規定,超過 3 次重試視為永久失敗
| 類型 | 慣例 | 範例 |
|---|---|---|
| 變數、參數、函式、方法 | camelCase,小寫開頭 | userName, getUserList() |
| 建構函式、類別 | PascalCase,大寫開頭 | User, HttpClient |
| 常數 | UPPER_SNAKE_CASE | API_BASE_URL |
| 私有成員(慣例) | 底線開頭 _ | _internalCache |
| 系統/內建相關(慣例) | 美元符號開頭 $ | $element (jQuery 物件) |
**避免**使用單字母變數(迴圈索引 i, j 除外)、拼音、中文拼音命名。
const / let**,棄用 var(ES6+ 環境)。// 範例
function processOrder(order) {
const discountRate = 0.1;
const isMember = order.user.isMember;
const shippingFee = calculateShipping(order.address);
// ...
}
function name(;右括號與左大括號間留一空格 ) {。function () {(function 與 ( 間留空格)。'use strict'; 或模組自動啟用。eval()、with、arguments.callee。=== / !==,避免隱含型別轉換。持續遵循規範、善用靜態分析工具、定期 Code Review,才能讓 JavaScript 專案在長期演進中保持健康。