萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

JavaScript 編碼規範完整指南:從排版、命名到最佳實踐

JavaScript 語法靈活寬鬆,若缺乏規範,極易產生難以維護的「義大利麵代碼」。本文整理業界公認的編碼規範,涵蓋檔案組織、排版、命名、宣告、註解等面向,助您撰寫高品質、可長期維護的程式碼。

一、檔案組織與引用

1. 獨立 .js 檔案

所有 JavaScript 程式應置於獨立 .js 檔,透過 <script src="filename.js"></script> 引入。避免在 HTML 內嵌腳本,以利快取、壓縮與維護。

2. 腳本置底載入

<script> 標籤應放在 </body> 之前,避免阻塞頁面渲染。若需在 <head> 載入,請加上 defer 或 async 屬性。

二、程式碼排版

1. 行長度限制

每行不超過 80 字元(現代螢幕可放寬至 100-120)。過長行應換行,下一行縮進 8 空格(或 2 個縮進層級),與區塊縮進(4 空格)區分。

2. 分號結尾

**務必**在每個陳述式結尾加上分號。雖然 ASI(自動分號插入)機制存在,但明確分號可防止壓縮、合併檔案時發生錯誤。

3. 換行位置

換行應在運算子、逗號**之後**進行,而非變數名、字串、數字或 ) ] ++ -- 之後。

// 推薦
const valueC = valueA +
               valueB;

// 不推薦
const valueB = valueA
               + valueC;

4. 縮進統一使用 4 空格

**禁止使用 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_CASEAPI_BASE_URL
私有成員(慣例)底線開頭 __internalCache
系統/內建相關(慣例)美元符號開頭 $$element (jQuery 物件)

**避免**使用單字母變數(迴圈索引 i, j 除外)、拼音、中文拼音命名。

五、變數與函式宣告

1. 變數宣告

  • **嚴格使用 const / let**,棄用 var(ES6+ 環境)。
  • 函式開頭集中宣告區域變數,按字母序排序,每行一個,便於加註解。
  • 未宣告直接賦值會建立全域變數,嚴禁。
// 範例
function processOrder(order) {
  const discountRate = 0.1;
  const isMember = order.user.isMember;
  const shippingFee = calculateShipping(order.address);
  // ...
}

2. 函式宣告

  • 函式名與左括號緊鄰 function name(;右括號與左大括號間留一空格 ) {。
  • 匿名函式表達式:function () {(function 與 ( 間留空格)。
  • 內部函式置於變數宣告之後,清楚界定作用域。

六、其他關鍵規範

  • 嚴格模式:檔案頂部加入 'use strict'; 或模組自動啟用。
  • 避免 eval()、with、arguments.callee。
  • 比較運算子優先用 === / !==,避免隱含型別轉換。
  • 減少全域汙染:採用 IIFE、ES Modules 或命名空間封裝。
  • 工具輔助:整合 ESLint + Prettier + EditorConfig,CI 流程強制檢查。

七、參考資源

持續遵循規範、善用靜態分析工具、定期 Code Review,才能讓 JavaScript 專案在長期演進中保持健康。

copyright © 萬盛學電腦網 all rights reserved