程式碼範例樣式規範

本文件將說明如何在說明文件中納入程式碼範例 以及程式碼範例的特定樣式規範具體措施包括：

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

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

程式碼範例最佳做法

為熟悉的 Fuchsia 部分建立程式碼範例時 思考新使用者會如何閱讀樣品，並預測其需求。 從整個過程思考流程，包括完成流程的必要步驟 並指定成功標準

舉例來說，建議您在開始使用前，先評估所有必要資訊 並導入程式碼範例請確認您並未忽略使用「 但在日常工作流程中消失了。

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

同樣地，請務必在使用者順利完成 正確指定程序。如要提升使用者對樣本的信心，請務必 指定使用者的程式碼應如下所示，以及使用者可以如何確認他們 已成功執行樣本。

程式碼範例檢查清單

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

• 提供「必備條件」部分，這是 。 從內部收集必要資訊 說明文件，在使用者啟動程序之前，阻止使用者 就不會受到不必要的封鎖或感到困擾
  • 必備資訊可能包含下列任一項目：
    • 編輯環境變數。
    • 請先執行必要的指令碼，再啟動程序。
    • 取得裝置存取權。
    • 包含 BUILD 依附元件。
    • 匯入程式庫。
• 連結至現有說明文件 (如適用)。 例如，記錄過程的先決條件 可能是 Fuchsia 有舖設的目標裝置。 與其重覆鋪陳裝置，不如連結至現有裝置 fuchsia.dev 中的「已舖設」主題， 例如「建構及貼上快速入門導覽課程」
• 如果您擁有以下狀態，請避免使用 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());
  }
  …

確認成功

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

在操作指南中新增一個部分，指示開發人員如何確認 他們也成功實行了程序如果可以的話，這個部分 當中包含預期結果的終端機輸出內容。這有助於提高 提升他們的信心

請參閱以下範例，確認程式碼範例中的成功與否。

範例