程式碼範例樣式規範

本文說明如何在文件中加入程式碼範例，以及程式碼範例的特定樣式規範。這些項目包括：

• 程式碼範例最佳做法
• 程式碼範例檢查清單
• 程式碼範例樣式指南

如需一般文件標準的相關資訊，包括檔案類型、位置和一般語氣，請參閱 Fuchsia 說明文件標準。如需關於字詞選擇、樣式和結構的具體指南，請參閱 Fuchsia 說明文件樣式指南。

程式碼範例最佳做法

為熟悉的 Fuchsia 部分建立程式碼範例時 思考新使用者會如何閱讀樣本，並預測其需求。 請思考整個程序，並納入完成程序的必要步驟，並明確說明成功的樣貌。

舉例來說，建議您在開始使用前，先評估 並導入程式碼範例請確認您不會忽略使用範例所需的資訊，但在日常工作流程中不再出現。

這可能是因為你已經完成這些步驟的次數過多 不可能成為程序所需的重要角色其他可能的原因 您只需要填寫一次必要資訊，因此 你在撰寫說明文件時無法記得這些步驟如果可以，請嘗試執行 先行檢查，並確認您具備所有必備條件 資訊。

同樣地，當使用者正確完成特定程序時，也請務必讓他們知道。如要提升使用者對樣本的信心，請務必 指定使用者程式碼的外觀，以及使用者可以如何確認 已成功執行樣本。

程式碼範例檢查清單

如果您要在說明文件中加入程式碼範例，請參閱下列資訊 清單後再提交貢獻內容，為確保程式碼範例清楚易懂：

• 提供「必備條件」部分，這是 。 在使用者啟動程序前，先在說明文件中收集必要資訊，可避免使用者遭到不必要的阻斷或感到挫折。
  • 必備資訊可能包含下列任一項目：
    • 編輯環境變數。
    • 在開始程序前執行必要指令碼。
    • 取得裝置存取權。
    • 包含 BUILD 依附元件。
    • 匯入程式庫。
• 連結至現有說明文件 (如適用)。 例如，記錄過程的先決條件 可能是 Fuchsia 的刷新目標裝置。 請不要重述如何刷新裝置，而是連結至 fuchsia.dev 上現有的「Flash」主題，例如建構並刷新 Fuchsia。
• 如果程式碼範例中包含預留位置，請避免使用 foo、bar 或其他模糊的預留位置名稱。請改用可表達該預留位置在程式碼中功能的名稱。詳情請參閱「避免使用含糊的預留位置」。
• 明確指出這部分，就是讓開發人員在流程中安穩。 預期有人可能會在未充分閱讀的情況下執行程式碼範例 。因此，請確認您的程式碼範例在空間範圍內 清楚掌握現況詳情請參閱「指定刊登位置」。
• 結束各個部分時，提供程式碼範例摘要，詳細說明程序中特定位置的完成程式碼應為何種樣貌。詳情請參閱「指定刊登位置」和「確認成功」。
• 說明測試程序所需的步驟，並展示成功的終端機輸出內容。

程式碼範例樣式指南

以下是可行的最佳做法，可協助您在說明文件中建立易於理解的程式碼範例。

避免使用模糊的預留位置

程式碼範例預留位置名稱和值應代表本身的用途 程式碼，避免使用 foo 和 bar 等抽象預留位置。

• 使用預留位置名稱來表示預留位置函式的意義 。 這樣一來，開發人員就能參考實際範例，日後再回頭查看。

• 程式碼範例應可複製到終端機並成功執行，而無須使用者大幅修改。

請參考以下範例，瞭解如何避免使用模糊的預留位置。

範例

protocol: "fuchsia.example.Foo"

  use: [
    {
      protocol: "fuchsia.process.Launcher"
    }
  ]

指定刊登位置

程式碼範例應指定該程式碼應位於特定檔案中的哪個位置。

舉例來說，如果程式碼行應位於特定函式中，則程式碼範例應展示該空間順序，而非在沒有背景資訊的情況下顯示該程式碼行。

請參閱指定程式碼位置的範例。

範例

syslog::fx_log_info!("{}, log!", greeting());

syslog::fx_log_info!("{}, log!", greeting());

  use fuchsia_syslog as syslog;

  fn main() {
      syslog::init().expect("should not fail");
      syslog::fx_log_info!("{}, log!", greeting());
      println!("{}, world!", greeting());
  }
  …

確認成功

使用者如果對新程序不甚熟悉， 您正確完成該程序，即使 已完成所有記錄的步驟

在操作說明中加入一節，說明開發人員如何確認已成功實作程序。這個部分應盡可能納入預期結果的終端機輸出內容。這有助於提高 提升他們的信心

請參考以下程式碼範例，瞭解如何確認成功。

範例