編寫程式碼示例的指南

本節介紹了建立易於理解的最小程式碼示例以演示特定功能或函式用法的最佳實踐。

您新增到 MDN Web 文件的程式碼示例應

• 足夠簡單，易於理解，但
• 足夠複雜，可以做一些有趣的事情，最好是有用的。

您需要牢記的一項首要考慮因素是：讀者會將程式碼示例複製貼上到他們自己的程式碼中，並可能將其投入生產。

因此，您應確保程式碼示例可用，遵循普遍接受的最佳實踐，並且不做任何會導致應用程式不安全、效率低下、臃腫或無法訪問的事情。如果程式碼示例不可執行或不適合生產環境，請務必在程式碼註釋和解釋性文字中新增警告；例如，如果它只是一個程式碼片段而不是完整的示例，請明確說明。這也意味著您應提供所有執行示例所需的資訊，包括任何依賴項和設定資訊。

程式碼示例應儘可能自包含且易於理解。目標不一定是編寫出讓專家印象深刻、功能強大的高效、巧妙的程式碼，而是編寫出儘可能快地理解的簡化的工作示例。

一些更通用的最佳實踐包括

• 程式碼示例應簡短，理想情況下只顯示您立即感興趣的功能。
• 只包含對示例必不可少的程式碼。大量的無關程式碼很容易分散讀者注意力或讓他們感到困惑。如果您想提供一個完整的、更長的示例，請將其放在我們的 GitHub 程式碼庫（或 JSBin、Codepen 或類似工具）中，然後在示例的上方或下方提供完整版本的連結。
• 不要包含不必要的伺服器端程式碼、庫、框架、預處理器和其他此類依賴項。它們會降低程式碼的可移植性，並使程式碼更難執行和理解。儘可能使用原生程式碼。
• 不要假設讀者瞭解任何庫、框架、預處理器或其他非原生功能。例如，使用在示例中具有意義的類名，而不是對 BEM 或 Bootstrap 使用者有意義的類名。
• 儘可能編寫整潔易懂的程式碼，即使它不是編寫程式碼的最有效方式。
• 在您的程式碼示例中要具有包容性；考慮到 MDN 的讀者來自世界各地，並且在種族、宗教、年齡、性別等方面都具有多樣性。確保程式碼示例中的文字反映這種多樣性，並且對所有人具有包容性。
• 不要為了簡潔而使用不良實踐（例如 <big> 或 document.write() 等演示元素）；正確地執行它。
• 在 API 演示的情況下，如果您同時使用多個 API，請指出包含哪些 API 以及哪些功能來自哪裡。

關於正確縮排、空格和行長的意見一直存在爭議。關於這些主題的討論會分散建立和維護內容的注意力。

在 MDN Web 文件中，我們使用 Prettier 作為程式碼格式化程式，以保持程式碼風格的一致性（並避免無關的討論）。您可以參考我們的 配置檔案 以瞭解當前規則，並閱讀 Prettier 文件。

Prettier 會格式化所有程式碼並保持風格的一致性。儘管如此，您仍需遵循一些額外的規則。

這些 MDN Web 文件格式化程式碼示例的指南也是您編碼時的良好實踐。

為了確保程式碼塊的正確格式和語法高亮，作者必須指定他們正在編寫的程式碼塊的語言。請參閱 MDN Markdown 中的示例程式碼塊，瞭解 MDN 支援的語言列表以及有關如何請求新語言的詳細資訊。

如果程式碼塊是虛擬碼、命令的輸出或其他非程式語言，請明確將語言設定為 plain。

• 程式碼行不應該太長，以至於需要水平滾動才能閱讀。
• 作為推薦做法，將程式碼行長度保持在 80 個字元以內（對於 互動式示例，則為 64 個字元）。
• 為了可讀性，在自然斷點處換行，但不要以犧牲最佳實踐為代價。

例如，這不太好

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.`;

if (
  obj.CONDITION ||
  obj.OTHER_CONDITION ||
  obj.SOME_OTHER_CONDITION ||
  obj.YET_ANOTHER_CONDITION
) {
  /* something */
}

const toolkitProfileService = Components.classes[
  "@mozilla.org/toolkit/profile-service;1"
].createInstance(Components.interfaces.nsIToolkitProfileService);

程式碼塊應該儘可能長，但不要更長。理想情況下，目標是 15-25 行左右的短程式碼塊。如果程式碼塊要長得多，請考慮只顯示最有用的程式碼片段，並將完整示例的連結放在 GitHub 程式碼庫或 CodePen 上。

內聯程式碼格式

使用內聯程式碼語法 (`) 標記函式名、變數名和方法名。例如："frenchText() 函式"。

方法名後應緊跟一對圓括號：例如，doSomethingUseful()。圓括號有助於將方法與其他程式碼術語區分開來。

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

• 將寬度設定為 100%：MDN Web 文件上的主要內容窗格在桌面上的寬度約為 700 畫素，因此嵌入式程式碼示例必須在該寬度下看起來正常。
• 將高度設定為低於 700 畫素：我們建議將渲染的程式碼示例寬度保持在該高度範圍內，以最大限度地提高螢幕上的可讀性。

• 使用關鍵字表示主要顏色和其他“基本”顏色，例如
  css

  color: black;
  color: white;
  color: red;
  

• 對於更復雜的顏色（包括半透明顏色），請使用 rgb()
  css

  color: rgb(0 0 0 / 50%);
  color: rgb(248 242 230);
  

• 對於十六進位制顏色，請在相關情況下使用簡短形式
  css

  color: #058ed9;
  color: #a39a92c1;
  color: #ff0;
  color: #fbfa;
  

  css

  color: #ffff00;
  color: #ffbbffaa;
  

您會注意到，在本頁面上，代表要遵循的最佳實踐的程式碼塊在右上角用一個綠色的勾號渲染，而演示不良實踐的程式碼塊則用一個紅色圓圈中的白色叉渲染。

您可以在編寫程式碼示例時遵循相同的風格。您不需要在任何地方都使用這種風格——只在您希望在程式碼示例中特別指出良好和不良實踐的頁面上使用即可。

要獲得這種渲染效果，請使用“程式碼圍欄”來界定程式碼塊，並在後面加上語言資訊字串。例如

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

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

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

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

這些將被渲染為

<p class="brush: js example-good"></p>

<p class="brush: js example-bad"></p>