編寫程式碼示例的指南

程式碼示例的通用原則

您需要牢記一個最重要的考慮因素：讀者會複製貼上示例到他們自己的程式碼中，並可能將其投入生產。 因此，您應該確保程式碼示例是可用的，遵循普遍接受的最佳實踐，並且不會導致應用程式出現不安全、效率低下、臃腫或不可訪問的情況。

如果程式碼示例無法執行或不適用於生產環境，請在程式碼註釋和解釋性文字中包含警告；例如，如果它只是一個片段而不是完整的示例，請清楚地說明這一點。這也意味著您應該提供執行示例所需的所有資訊，包括任何依賴項和設定資訊。

程式碼示例應足夠簡潔易懂，但又足夠複雜能做一些有趣且（最好是）有用的事情。其目的不一定是製作出能給專家留下深刻印象、功能強大且高效的程式碼，而是分享可以快速理解和學習的、簡化的可執行示例。

一些更通用的指南包括

• 程式碼示例應簡短，並且最好只展示您當前感興趣的功能。
• 編寫程式碼時，請儘可能使其易於理解，即使它不是最高效的寫法。
• 不要包含不必要的伺服器端程式碼、庫、框架、預處理器和其他此類依賴項。它們會使程式碼更難移植，也更難執行和理解。儘可能使用原生程式碼。
• 不要假設讀者瞭解任何庫、框架、預處理器或其他非原生功能。例如，使用示例中具有意義的類名，而不是對於 BEM 或 Bootstrap 使用者有意義的類名。
• 在程式碼示例中做到包容；請記住 MDN 的讀者來自世界各地，並且在種族、宗教、年齡、性別等方面都多種多樣。確保程式碼示例中的文字反映了這種多樣性，幷包容所有人。
• 不要為了簡潔而使用已棄用的功能（例如 <big> 或 document.write() 等表示元素）；要正確使用。
• 對於 API 演示，如果您同時使用了多個 API，請指出其中包含了哪些 API，以及功能來自哪裡。

瀏覽器支援

在為尚未在所有主要瀏覽器中都可用的技術建立程式碼示例時，請考慮使用 特性檢測 來回退到更簡單的行為，或告知使用者他們的瀏覽器尚不支援。請勿在程式碼註釋或文字中指定支援的瀏覽器及其版本，因為這些資訊會很快過時。

MDN 程式碼風格和格式

關於正確縮排、空白和行長的意見一直存在爭議。對這些主題的討論會分散建立和維護內容的精力。在 MDN Web Docs 上，我們使用 Prettier 作為程式碼格式化工具，以保持程式碼風格的一致性並避免跑題的討論。您可以檢視我們的 配置檔案 來了解當前規則，並閱讀 Prettier 文件。

除了自動格式化之外，MDN 上的程式碼示例還有一些其他規則，以確保最終能得到良好的渲染。

選擇正確的語言

為確保程式碼塊的正確格式化和語法高亮，請正確指定程式碼塊的語言。請參閱 MDN Markdown 中的示例程式碼塊，瞭解 MDN 支援的語言列表以及如何請求新語言的詳細資訊。

如果程式碼塊是虛擬碼、命令的輸出，或者不是程式語言，請將語言設定為 plain

```plain
StaleElementReferenceException: The element reference of ABD-123 is stale…
```

程式碼行長度

程式碼行不應過長以至於需要水平滾動才能閱讀。為了可讀性，請在自然的斷點處換行，但不要犧牲最佳實踐。例如，這樣並不好

let tommyCat =
  "Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.";

這樣更好，但有些彆扭

const tommyCat =
  "Said Tommy the Cat as he reeled back to clear whatever foreign " +
  "matter may have nestled its way into his mighty throat. Many a fat alley rat " +
  "had met its demise while staring point blank down the cavernous barrel of " +
  "this awesome prowling machine.";

使用模板字面量會更好

const tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign
  matter may have nestled its way into his mighty throat. Many a fat alley rat
  had met its demise while staring point blank down the cavernous barrel of
  this awesome prowling machine.`;

程式碼塊高度

程式碼塊應與所需長度相同，不多不少。理想情況下，目標是簡短，例如 15-25 行。如果程式碼塊會更長，可以考慮顯示最有用的部分，並將完整的示例連結到 GitHub 倉庫、Gist 或 CodePen 等地方。

行內程式碼格式化

使用行內程式碼語法來標記函式名、變數名和方法名。例如，“frenchText() 函式”在 markdown 中寫為

the `frenchText()` function

方法名後面應跟一對括號：例如，doSomethingUseful()。括號有助於區分方法和其他程式碼術語。

正確渲染的指南

應遵循這些指南，以確保您編寫的程式碼示例在 MDN Web Docs 上正確顯示。您還應考慮響應式設計，使程式碼示例在移動裝置上也能使用。

渲染的程式碼示例大小

• 寬度設定為 100%：MDN Web Docs 上的主內容區域在桌面上的寬度約為 700px，因此嵌入的程式碼示例必須在該寬度下看起來良好。
• 高度設定為低於 700px：我們建議將此高度用於渲染的程式碼示例寬度，以獲得最佳的螢幕可讀性。

突出顯示好的或壞的示例

您會注意到在此頁面上，代表良好實踐的程式碼塊在右角會顯示綠色的對勾標記，而演示不良實踐的程式碼塊則顯示紅圈中的白色叉號。

您可以在編寫程式碼示例時遵循相同的樣式。您不必在所有地方都使用此樣式 — 只需在您想專門強調程式碼示例中良好和不良用法的地方使用。

程式碼塊使用 markdown 中的“程式碼圍欄”來分隔程式碼塊，後面跟資訊字串中的語言。例如

```js
function myFunc() {
  console.log("Hello!");
}
```

為了將程式碼塊表示為好或壞的示例，請在語言字串後新增 example-good 或 example-bad，如下所示

```html example-good
<p>Good example</p>
```

```html example-bad
<p>Bad example</p>
```

這些將渲染為

<p>Good example</p>

<p>Bad example</p>

佔位符文字使用指南

使用從 lipsum.com 生成的 lorem-ipsum 佔位符文字，或 Lorem ipsum VS Code 外掛。標準的 lorem-ipsum 文字包含在我們的拼寫檢查器配置中，因此在 IDE 或程式碼審查期間的測試中不會被報告為拼寫錯誤。使用一致的佔位符文字使示例程式碼更易於審查，尤其是在重複出現時。它還有助於使示例清晰地用於說明目的，並避免因無關內容分散讀者的注意力。