FIDL 樣式指南

這個部分包含以下項目的樣式相關資訊： Fuchsia Interface Definition Language 檔案。

另請參閱 FIDL API 評分量表。

名稱

貓的命名並不容易，
不是只有一場節慶遊戲。
--- T.S.Eliot

在 FIDL 中定義的名稱，會用來產生每種譯文語言的 ID。 部分語言會在不同的名稱中附加語義或傳統意義 表單。例如，在 Go 中，ID 中的初始字母是否 大寫會控制 ID 的顯示設定。因此 語言後端會轉換您程式庫中的名稱，使其更加 打造適合目標語言的內容本節中的命名規則是 在 FIDL 來源的可讀性和各目標的可用性之間取得平衡 以及目標語言的一致性

請避免使用常用的字詞，例如 goto。語言後端 將保留字詞轉換為非保留 ID，但這些轉換 減少這些語言的可用性避免使用常見的保留字詞，可以減少 套用這些轉換的頻率

儘管某些 FIDL 關鍵字在目標語言中也是常見的保留字詞， (例如 C 和 C++ 中的 struct)，因此應避免使用其他 FIDL 關鍵字 (尤其是 request 和 handle) 通常是描述性字詞 您也可以視需要使用這些選項

名稱的開頭或結尾不得為底線。開頭或結尾 在某些語言中，底線 (例如開頭的底線) 具有語意含意 控制 DoubleClick 的可見性) 和其他語言 (例如 在 C++ 中，結尾的底線常用於成員變數。 此外，FIDL 編譯器會使用開頭和結尾的底線，以便統一處理 識別碼可避免衝突。

請使用 size 字詞為位元組數命名。請使用 count 這個字詞來命名 其他數量 (例如 結構體)。

案件定義

有時候，Google Analytics 中的 識別碼樣式如下：

• 請使用英文 (美國) 的原始詞組 (例如「非空值 HTTP 用戶端」)
• 請移除所有標點符號。(「非空值 HTTP 用戶端」)
• 全部改為小寫 (「非空值 http 用戶端」)
• 視指定的樣式，執行下列任一操作 ID：
  • 針對小寫蛇形大小寫，並以底線 (「_」) 取代空格 (non_null_http_client)。
  • 大寫字體，並以底線取代空格 (NON_NULL_HTTP_CLIENT)。
  • 每個字的首字母大寫，然後將所有單字合併在一起，以 大寫駝峰式大小寫 (NonNullHttpClient)。

用量

下表將案例使用情形對應至 元素：

程式庫

程式庫名稱是以半形句號分隔的 ID 清單。圖書館的部分內容 也稱為命名空間每個元件的 名稱必須為小寫，且必須符合下列規則運算式： [a-z][a-z0-9]*。

由於不同的目標語言各有不同，因此我們使用上述限制性規則 限制命名空間、程式庫或套件評估方式。我們 選用保守的最小公分母，FIDL 才能順利運作 搭配現行的指定語言組合，以及潛在的未來目標 語言。

ID 名稱：偏好具有意義的功能角色

優先使用函式名稱 (例如fuchsia.media) 高於產品或代碼名稱 (例如：fuchsia.amber 或 fuchsia.scenic)。建議使用合適的產品名稱 當產品對於 Fuchsia 以外的外部存在， 專屬通訊協定例如，fuchsia.cobalt 是 Cobalt 介面通訊協定的名稱優於 fuchsia.metrics 其他指標的導入方法 (例如Firebase) 不太可能導入 因此效能相當卓越

ID 名稱應與參與者扮演的特定角色有關。 避免對名稱進行編碼存取控制依據角色分類的名稱 名稱不會因存取權控管而異，且不會如預期般迅速更新， 指涉外部定義的關係，此關係可能會隨著 不斷進化舉例來說，如果 API 涉及 FocusChain 物件， 適當名稱應為 fuchsia.ui.focus，而不是 fuchsia.ui.privileged；如果我們決定將 FocusChain 物件擴大 表示 fuchsia.ui.focus 不是問題名稱，下列 範例字詞 應避免使用：

• constrained
• limited
• oem
• private
• privileged
• protected
• special
• vendor

ID 名稱應具有意義；避免使用無意義的名稱如果 fuchsia.foo.bar 和 fuchsia.foo.baz 都分享了一些概念 建議在獨立的程式庫中 fuchsia.foo而非 fuchsia.foo.common。下列範例字詞 請避免：

• common
• service
• util
• base
• f<letter>l
• zx<word>

頂層

避免重複使用程式庫名稱中的名稱。例如，在 fuchsia.process 程式庫，啟動程序的通訊協定應命名 Launcher 而非 ProcessLauncher，因為「process」這個名稱已經存在 。在所有目標語言中，頂層名稱都是 界定範圍是程式庫名稱的範圍

原始別名

原始別名不得與封閉資料庫中的名稱重複。所有 目標語言，原始別名會替換為基礎原始別名 因此不會造成名稱衝突。

alias vaddr = uint64;

常數

常數名稱不得與外圍程式庫中的名稱重複。在所有目標區間內 常數名稱的範圍取決於其內附程式庫。

用來說明下限和上限的常數應使用前置字串 MIN_ 和 MAX_。

const MAX_NAMES uint64 = 32;

通訊協定

通訊協定是透過 protocol 關鍵字指定。

通訊協定必須為名詞片語。 通訊協定通常是以建議動作的名詞命名。適用對象 例如，AudioRenderer 是名詞，表示通訊協定相關 才能轉譯音訊同樣地，Launcher 是名詞，表示 與啟動項目有關通訊協定也可以 尤其是與實作所持有州名相關的名詞。 例如，Directory 是名詞，表示通訊協定會用於 與實作中的目錄互動。

通訊協定能以物件導向設計模式命名。例如： fuchsia.fonts.Provider 使用 provider 後置字串，表示 通訊協定提供的是字型，而不是代表字型本身。同樣地 fuchsia.tracing.Controller 使用 controller 後置字串，表示 通訊協定會控制追蹤系統 (而不是代表追蹤 其本身)。

「Manager」這個名稱可做為含有 例如：fuchsia.power.Manager。不過請注意 「管理員」通常會吸引大量鬆散的通訊協定 這類功能可能更適合納入多個通訊協定。

通訊協定不得含有名稱 service.。所有通訊協定都會定義服務。 這個字詞沒有任何意義。舉例來說，fuchsia.tts.TtsService 違反了 評分量表首先，Tts 前置字串與程式庫重複 名稱。第二，Service 字尾是禁止的。

明確「open/ajar/closed」修飾符

請務必指定通訊協定，應一律指定 open、ajar 或 closed 不必仰賴預設值也就是說，一律將 open protocol Foo { ... 設為只使用 protocol Foo { ...。

方法

方法必須為動詞片語。

舉例來說，GetBatteryStatus 和 CreateSession 是 指出該方法執行的動作。

事件時呼叫的 listener 或 observer 通訊協定的方法 應該以 On 做為前置字元，並說明 時態例如，ViewContainerListener 通訊協定有一個方法 OnChildAttached。

活動

同樣的，事件 (例如從伺服器傳送至用戶端的來路不明郵件) 應加上 On 的前置字串，並說明過去發生的事件 緊張刺激。

舉例來說，AudioCapturer 通訊協定包含一個名為 OnPacketCaptured。

單一方法通訊協定

其中一種方法通訊協定的方法應為 所定義通訊協定的名詞片語，例如Loader.Load、Getter.Get、 Uploader.Upload。如果是限定名詞片語，例如 JobCreator 或 ProcessStopper，請使用不合格的動詞詞組，例如 JobCreator.Create或ProcessStopper.Stop。

單純是單一方法的通訊協定，但預計會隨著時間演進多方法 不一定需要遵循這個命名慣例 非建議命名的通訊協定擴充欄位 建議盡早選擇其他名稱位於 也不需要遵循預設的建議。

因為取代通訊協定比改進通訊協定困難 因而需要改用多種方法 因此建議您新增方法，將現有的通訊協定演進。 且可能重新命名現有方法

煽情露骨內容「strict/flexible」修飾符

對於方法和事件，請一律指定 strict 或 flexible 不必仰賴預設值也就是說，一律將 flexible Foo(); 設為 只要 Foo()。

結構、聯集和表格

結構體、聯集和資料表必須為名詞片語。 舉例來說，Point 是定義了空間中的位置的結構， KeyboardEvent 是定義鍵盤相關事件的結構體。

結構、聯集和資料表成員

使用單一字詞時，優先使用 struct、聯集和資料表成員名稱 實在 (單字名稱在所有目標語言的搜尋結果中較為一致)。 但是，如果單一字詞的 內容模糊或混淆。

成員名稱不得重複從所屬類型 (或資料庫) 中重複使用，除非 但不包含所屬類型中的名稱，所以會員名稱不明確。適用對象 例如，KeyboardEvent 類型的成員只要包含事件發生的時間 傳遞的檔案名稱應為 time，而不是 event_time，因為名稱 event 已出現在所屬類型名稱中。在所有目標區間內 成員名稱取決於其包含類型

然而，DeviceToRoom 類型會將智慧型裝置與會議室建立關聯 這個工作區位於 ，可能需包含 device_id 和 room_name 成員，因為 「id」和「name」不正確。其中一項可能就是 或是房間或某個房間

列舉

列舉必須是名詞片語。

舉例來說，PixelFormat 這個列舉會定義顏色編碼方式 轉換為圖像中的位元

列舉成員

列舉成員名稱不得與外圍類型 (或資料庫) 中的名稱重複。 舉例來說，PixelFormat 列舉的成員應命名為 ARGB，而非 PIXEL_FORMAT_ARGB，因為名稱中已有「PIXEL_FORMAT」這個名稱 就屬於封閉類型在所有目標語言中，列舉成員名稱的範圍都是 其包圍類型

比特田

位元欄位必須為名詞片語。

舉例來說，InfoFeatures 是位元欄位，用於指出哪些地圖項目 都會出現在乙太網路介面上

Bitfield 成員

Bitfield 成員的類型 (或程式庫) 中不得使用重複名稱。 舉例來說，InfoFeatures 位元欄位的成員應命名為 WLAN 而非 INFO_FEATURES_WLAN，因為「INFO_FEATURES」名稱已存在 會顯示在封閉類型的名稱中 在所有目標語言中，位元欄位成員名稱的範圍都是 封閉類型。

類型

煽情露骨內容「strict/flexible」修飾符

適用於接受 strict/flexible 修飾符的類型 (bits、enum 和 union)，因此應一律指定這類修飾符，而非依賴 預設值。也就是說，一律將 flexible bits ... 設為只使用 bits ...。

機構

語法

• 使用 4 個空格縮排。
• 不使用分頁。
• 避免在結尾加上空白字元。
• bits、enum、protocol、struct、table 和 和 union 則來自其他宣告 一行空白行 (兩個連續的換行字元)。
• 僅有一個換行字元的檔案結尾。

留言

註解使用 /// (三個正斜線)。媒體庫中的註解也會 才會出現在系統產生的程式碼中，方便您在根據 資源庫。表示留言會「流暢」翻譯成目標語言

將意見放在描述內容上方。除了所列案例以外 請使用適當的大小寫和正確的句子， 。除非留言較長，否則留言寬度限制在 80 個字元以內 難以避免的情況 (例如，過長的網址)。

註解應使用 Markdown 撰寫。我們仰賴 Markdown 的 CommonMark 規格。只有部分通知 工具可能會使用其他 Markdown 標準轉譯輸出內容。為了讓你的工具 並未使用 CommonMark，我們鼓勵開發人員撰寫 Markdown 可與 CommonMark 及其工具相容參照 FIDL 元素 一律使用程式碼字型。

記錄實體是指任何有附加註解的 FIDL 元素。第一個 應提供註解中任何文件實體的參考資料 合格名稱，格式為 [`<library>/<top level declaration>.<member>`] (例如：[`fuchsia.io/Node.clone`])。如果 部分工具後續參照該文件實體時， 使用縮寫，但前提是內容不明確 (例如：clone)。不含括號的表單不會產生超連結。

請求參數、回應參數和錯誤類型應記錄為 表單清單：

+ request `param1` <description>
+ request `param2` <description>
- response `param1` <description>
- response `param2` <description>
* error <description>

要求、回應和錯誤必須依序顯示。一組指定的 參數也必須遵循 參數清單「要求」一詞和「response」而不需加以顯示 參數名稱只會出現在其中一個要求或回應參數清單中。

文件註解中，用來描述變數、欄位或類型的第一部分應為 用來簡短陳述文件所列實體預期用途的名詞片語。 包括無法從名稱和類型中估算出的資訊。 說明必須以句點結尾說明不得 重複記錄實體的名稱，或該實體的特定類型 FIDL 語言元素 (例如struct 或 protocol)。

/// A representation of violins displayed on the screen.
type Widget = struct {
    /// A monotonically increasing id, uniquely identifying the widget.
    id uint64;
    /// Location of the top left corner of the widget.
    location Point;
};

以下列舉幾個不得採取的行動：

/// BAD: Widget is a representation of violins displayed on the screen.
/// BAD: struct Widget is a representation of violins displayed on the screen.

文件註解附加至通訊協定方法的第一部分應為簡短 該方法行為的說明，從動詞開頭，包括 從名稱和類型中無法估算出的資訊。動詞應該是 看正確的人稱代名詞 使用直陳語氣 (這實際上意味著您應該假裝 「it」而您要做的是事實聲明)。 詞組的結尾應為句號

完整範例：

/// An abstract representation of a [`fuchsia.io/Node`] whose layout is flat.
protocol File {
    compose Node;

    /// Acquires a [`fuchsia.mem/Buffer`] representing this file, if
    /// there is one, with the requested access rights.
    ///
    /// ## Rights
    ///
    /// This method requires the following rights:
    ///
    /// * [`fuchsia.io/OPEN_RIGHT_WRITABLE`] if `flags` includes
    ///   [`fuchsia.io/VMO_FLAG_WRITE`].
    /// * [`fuchsia.io/OPEN_RIGHT_READABLE`] if `flags` includes
    ///   [`fuchsia.io/VMO_FLAG_READ`] or [`fuchsia.io/VMO_FLAG_EXEC`].
    ///
    /// + request `flags` a bit field composing any of
    ///     `VMO_FLAG_READ`, `VMO_FLAG_WRITE`, or `VMO_FLAG_EXEC`.
    /// - response `buffer` the requested `fuchsia.mem/Buffer`, or
    ///     null if there was an error, or the buffer does not exist.
    /// * error a zx_status value indicating success or failure.
    /// * see [`fuchsia.mem/Buffer`]
    /// [`fuchsia.mem/Buffer`]:
    ///    https://fuchsia.googlesource.com/fuchsia/+/HEAD/sdk/fidl/fuchsia.io/
    GetBuffer(struct {
        flags uint32;
    }) -> (resource struct {
        buffer box<fuchsia.mem.Buffer>;
    }) error zx.Status;
};

某些外部可靠來源定義的類型或值應加上註解 參照外部事物例如使用 Wi-Fi 描述設定結構同樣地， 結構必須與 C 標頭中定義的 ABI 相符，請參照 C 標頭。

如要進一步瞭解註解應包含的內容，請參閱 API 說明文件評分量表。

參照 FIDL 通訊協定或通訊協定方法

提及 FIDL 通訊協定或其方法時，必須遵守 模式：

/// See fuchsia.library/ProtocolName.Method for more information.

參照與註解所在程式庫中的通訊協定時，程式庫 名稱可能維持不變：ProtocolName.Method。

同樣地，在與註解相同的通訊協定中參照方法時， 請保留程式庫名稱和通訊協定名稱：Method。

程式庫總覽

您可以透過說明文件註解， library 陳述式。程式庫陳述式啟動 FIDL 檔案。例如：

/// Library containing example FIDL used throughout the Fuchsia documentation.
library fuchsia.examples.docs;

程式庫總覽應提供定義程式庫的一般說明文件。 他們也可能會針對各種訊息提供詳細的簡介 通訊協定，以及這些訊息與通訊協定如何搭配使用。

雖然一個程式庫可細分為多個 FIDL 檔案，但 只能設為單一程式庫總覽。請參考這些媒體庫的建議 總覽：

• 如果總覽很短，且資料庫內含單一檔案，您可以 請將總覽放在程式庫檔案頂端的 library 陳述式中。
• 如果程式庫包含多個檔案，請建立獨立檔案 overview.fidl 以記錄程式庫。「overview.fidl」檔案不得 包含任何宣告、類型別名或通訊協定定義。

非流量式留言

如果您是要給圖書館作者的留言，請提供更簡潔的註解 // (兩條正斜線)，不會流向目標語言。

決定要建立一般 /// 註解和非資料流動時 留言，請記住下列事項

定期留言：

• 參數、引數、函式的說明
• 使用須知

非流量式留言：

• 內部「待辦事項」留言
• 著作權聲明
• 導入作業詳細資料

這兩種類型的註解皆可合併：

/// A widget displaying violins on the screen.
// TODO -- widgets should use UUIDs instead of sequential ids
type ViolinWidget = struct {
    /// A monotonically increasing id, uniquely identifying the widget.
    id uint64;
    /// Location of the top left corner of the widget.
    location Point;
};

檔案

程式庫由一或多個檔案組成，檔案儲存在 並遵循以下慣例：

fidl/<library>/[<dir>/]*<file>.fidl

<library> 目錄是以 FIDL 的點分隔名稱命名 資源庫。<dir> 子目錄是選擇性的，通常不適用於 內含不到十幾個檔案的程式庫這個目錄結構符合 Fuchsia SDK 中包含 FIDL 檔案。

將程式庫分割為多個檔案，對 資源庫。宣告 (包括通訊協定) 可以彼此參照 整個程式庫中都適用。 將程式庫分成多個檔案，盡可能提升可讀性。

• 建議程式庫中的檔案使用 DAG 依附元件圖表。
• 建議讓雙向參照定義文字彼此靠近 最好放在同一個檔案中
• 如為複雜的程式庫，建議在分葉中定義純資料類型或常數 檔案，以及定義在主幹中參照這些型別的通訊協定 檔案。