程式碼範例樣式規範

本文件說明如何在說明文件中加入程式碼範例，以及程式碼範例的特定樣式指南。具體措施包括：

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

如要瞭解一般說明文件標準 (包括檔案類型、位置和一般色調)，請參閱 Fuchsia 說明文件標準。如需字詞選擇、樣式和結構的具體指南，請參閱「Fuchsia 說明文件樣式指南」。

程式碼範例最佳做法

針對您非常熟悉的 Fuchsia 部分建立程式碼範例時，請考慮新使用者如何閱讀範例，並嘗試預測他們的需求。請思考從端對端的過程，包括完成程序的事前準備步驟，並指定成功率。

舉例來說，在開始使用程式碼範例之前，請先考量所有必要必要資訊。請勿忽略使用範例的必要資訊，但也不再存在於日常工作流程中。

這可能是因為您已完成這些步驟的次數過多，導致這些步驟不再與程序的需求不同。也可能是因為這些必要資訊只需要填寫一次，因此在撰寫說明文件時就沒想到這些步驟。如果可以，請嘗試從頭開始執行範例，並確認您已已記錄所有必要資訊。

同樣地，請務必在使用者正確完成特定程序時通知使用者。如要提高樣本的使用者對信心，請務必指定使用者的程式碼外觀，以及使用者該如何確認已成功執行範例。

程式碼範例檢查清單

如要在說明文件中加入程式碼範例，請在提交貢獻前詳閱下列清單，確保程式碼範例清楚易懂：

• 加入「必備條件」一節，做為說明文件的第一部分。在使用者展開程序之前，先在說明文件中收集必要條件資訊，就能避免使用者受到不必要的封鎖或阻礙。
  • 必要條件資訊可能包括：
    • 編輯環境變數。
    • 在開始程序之前執行必要的指令碼。
    • 正在取得裝置存取權。
    • 包含 BUILD 個依附元件。
    • 正在匯入程式庫。
• 現有說明文件的連結 (如適用)。 舉例來說，您要記錄的程序條件可能是鋪面的 Fuchsia 目標裝置。請勿費時費力地攜帶自己的裝置，而是連結至 fuchsia.dev 中現有的「Pave」主題，例如「Build and Pepve quickstart」。
• 如要在程式碼範例中加入預留位置，請避免使用 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());
  }
  …

確認成功

使用者如未熟悉新程序，也很難知道是否已正確完成這項程序，即使您已完成所有記錄步驟也一樣。

在使用指南中加入一節，說明開發人員如何確認程序已成功實作。如果可以，這個部分應包含預期結果的終端機輸出內容。這麼做可以增加使用者的信心

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

範例