指令列工具評分量表

簡介

這份文件適用於指令列介面 (CLI) 工具。圖形使用者介面 (GUI) 不在範圍內。

開發 Fuchsia 工具時，可以使用特定的地圖項目和樣式來維持一致性。本文件將逐步說明這些需求。

我們的目標是讓 Fuchsia 開發人員工具維持一致的適配度，讓開發人員能掌握預期的情況。他們幾乎可以輕鬆瞭解如何完成常見工作，還可利用燈火通明的途徑找到罕見的工具。

指南

開發人員為 Fuchsia 編寫軟體的經驗會影響他們為平台撰寫內容的理解，而我們的工具是該體驗的重要部分。提供不一致 (且彼此不同) 的工具會導致開發人員體驗不佳。

本指南說明 Fuchsia 工具必須遵循的評分量表。

印尼盾

部分區塊會有「IDK」摘要，例如上方圖所示。這些詳細規則適用於 Fuchsia 整合商開發套件中隨附的工具。

注意事項

開始建立新工具之前，請先考量下列因素，以便判斷該工具是否適合 Fuchsia 或 Fuchsia SDK。

印尼盾

IDK 工具在某些方面是福奇亞專用。一般可用的通用工具或工具不應屬於 Fuchsia，且不會包含在 Fuchsia IDK 中。舉例來說，驗證一般 JSON 檔案的工具通常就不太實用。不過，可驗證使用 JSON 格式之 Fuchsia .cml 檔案的工具。

ffx

ffx 是 Fuchsia 的整合式 CLI 工具平台，用於指定互動目標。並提供以邏輯子指令為基礎的分組，與高階 Fuchsia 工作流程相互對應。還提供外掛程式架構，讓協作者展開 ffx 指令介面。ffx 是 Fuchsia IDK 的一部分發布。

目標對象

工具可用於不同的開發工作。在大型團隊中，這些角色可以是不同的人員以下是部分類別：

  • 元件開發
  • 駕駛開發 (DDK)
  • Fuchsia 開發 (SDK)
  • 版本整合 (GN 等)
  • 品質查驗 (QA)
  • 系統整合服務供應商 (例如裝置端網路工具)
  • 發布 (從開發主機到伺服器)
  • 部署作業 (從伺服器到客戶)

考量哪些使用者可能使用這項工具，並符合目標對象的需求。

工具在整合方面的期望可能有所不同。舉例來說，開發人員開發元件時，可能會預期工具會與其整合開發環境 (IDE) 整合，而建構整合工具則可以透過指令碼呼叫。

偏好在常見工具 (例如 ffx) 下放置相關指令。舉例來說，git、ffx 或 fx 會在單一使用者端指令下提供許多功能 (或「子工具」)。這有助於鼓勵團隊採用共用工作流程，並提供單一探索點。

偏好使用多個工具的子指令。例如，請勿建立具有連字號名稱 (例如 package-create 和 package-publish) 的工具，而是建立可接受建立及發布子指令的 package 指令。

讓工具中的指令數量保持井然有序且合理。也就是避免將與工具無關的指令加入工具，並在說明和說明文件中提供合理的指令組織。

工作範圍

指令列工具可分成兩個群組：簡易的單一用途工具和更強大的工具。請依據人體工學設計工具。簡單的工具應該能快速起步，而較複雜的工具則著重在更實用的工具。

大型工具會涵蓋整個使用者 (開發人員) 層級的工作。請避免使用能完成工作中小步驟的工具，而是製作能夠執行完整工作的工具。

例如：

  • 開發 C++ 應用程式：執行預先處理器、執行編譯器、執行連結器、啟動建構的執行檔。
  • 進行單元測試：建立測試並執行開發中的測試
  • 開發模組：編譯程式碼、將程式碼和資源移至裝置、啟動模組 (或熱重載)

專注在可完成預設必要步驟的工具，但進階使用者可以執行部分步驟 (例如傳遞引數，要求 C++ 編譯器僅執行預先處理器)。

印尼盾

如果是開發環境整合商和 EngProd 團隊，請分別使用不同的工具。建構整合商會學習每個做法並將其組合在一起，以打造出運作系統。

ffx

ffx 推出了許多子群組和相關子指令。一般來說，適合目標為指定互動、系統整合和發布的主機等類別的工具，建議擴充現有的 ffx 服務，而非新的獨立工具。這種情況可以透過其他旗標、選項或子指令擴充 ffx，藉此利用共用的程式碼和功能。如需注意事項和其他詳細資料，請參閱 ffx 開發總覽。

共用常見功能

如果有多個工具都需要一項任務中的一小部分，複製該程式碼並不合理。建議您建立小型支援工具，或建立程式庫來分享程式碼。

使用能夠執行特定工作步驟的小型工具，鼓勵重複使用程式碼。如果使用者不應分別執行這項小型工具，請將支援工具放在未新增至 $PATH 的目錄中。也就是避免對環境路徑產生不必要的汙染。

建議您提供程式庫來共用程式碼，這樣就不需要使用子程序。

實作

以下是建立工具的檢查要點。我們會說明編寫工具時使用的語言、該語言要使用哪種樣式等。

ffx

ffx 遵循以下所述的評分量表和慣例，並提供此處所列建議的參考實作。

命名

以下內容適用於二進位檔、工具、子指令和長參數標記的名稱。

使用美國英文詞彙或名詞做為名稱。知名的名詞包括用於主題的常見用途，或是整個子系統的名稱。如果名稱未顯示在說明文件中，表示名稱可能十分陌生。假如沒有任何實作項目顯示，那就絕對不是大家知道。

只能在 US-ASCII 字元集和連字號中使用小寫英文字母 (a-z)。單一連字號 (-) 是用來分隔名稱中的字詞。Platform 必要的擴充功能為例外狀況 (例如 .exe)。

使用超過三個字元命名 CLI 工具。請保留可供使用者捷徑使用的短檔案名稱 (別名)。如果您認為某項工具的名稱太短，請向 Fuchsia API 委員會申請核准。

請注意以上要點：

  • 使用全字而非縮寫。
  • 建議使用較短的名稱，因為使用者預期經常輸入名稱。針對較不常輸入的名稱自訂調整，則會調整為較明確的名稱。
  • 將一個字詞設為多個字詞
  • 偏好使用多個連字號工具的子指令 (例如避免使用 foo-start、foo-stop、foo-reset；而是使用可接受指令 start|stop|reset 的 foo)。
  • 除非引進毀損的隱喻，否則優先使用對稱 (尤其是動詞) 與其他類似指令或子系統的對稱。

程式語言

工具可能以 C++、Rust 和 Go 編寫。為求明確，以下列出一些未經核准的語言：Bash、Python、Perl、JavaScript 和 Dart (請參閱下方例外狀況)。

C++、Rust 和 Go 之間沒有語言偏好，其中要選擇哪一種語言是由工具的作者決定。

印尼盾

如果與 Fuchsia IDK 整合的 SDK 包含特定語言 (例如 Dart)，該語言可能會用於在該 SDK 發布的工具。換句話說，請勿在 SDK 中加入原本無法包含 Dart 執行階段的 Dart 工具，但如果已有 Dart 執行階段也沒關係。

樣式指南

請遵循對應的樣式指南，瞭解正在開發的 Fuchsia 語言和區域。舉例來說，如果工具包含在 Zircon 中並以 C++ 編寫，請使用 Zircon 中 C++ 的樣式指南。具體來說，請避免為工具建立個別的樣式指南。

請盡量減少執行階段連結依附元件 (請改為靜態連結依附元件)。在 Linux 中，可以針對 glibc 套件套件 (libm 等) 的執行階段連結；不允許其他執行階段連結依附元件。

從原始碼建構

請注意，部分開發人員會想使用原始碼打造工具。請使用與「平台來源樹狀結構」中的程式碼相同的建構和依附元件結構。請勿建立另一個系統來建構工具。

代管平台

留意工具耗用大量資源的情況，以及預期會在哪些 OS 上執行。

可在各種硬體上執行

開發人員機器可能從少數 CPU 核心和適量的 RAM 到數十個 CPU 核心和大量 RAM。請不要假設主機機器的功能強大，或者是否能使用伺服器叢集卸載工作。

支援的作業系統

為了方便讀者閱讀，本節內容。本文件不適用於支援的平台。

我們目前支援

  • 以 Debian 為基礎的 Linux 發行版 (其他 Linux 發行版可能可以正常運作，但系統並未正式支援)
  • macOS (x86 上目前未正式支援 M1)

專為開發人員編寫的工具必須在這些平台上執行。目前還有其他平台需要考慮，雖然目前並非強制規定，但建議您考量下列平台。

工具的建構方式應易於遷移至下列平台：

  • Fuchsia (自行託管)
  • Windows

這份清單僅列出部分示例，我們可能會支援其他地區。

不區分大小寫的檔案系統

請勿依靠檔案路徑區分大小寫的功能。例如：請勿預期 src/BUILD 和 src/build 是不同檔案。反過來說，由於某些平台會區分大小寫，因此請勿仰賴區分大小寫。

使用非英文語言代碼的開發主機

非英文開發人員需要考量幾個層面：

  • 工具本身是否可本地化
  • 工具的說明文件是否可本地化
  • 工具是否可使用包含非 ASCII 的路徑名稱及資料
  • 這項工具是否可在非英文的作業系統上正常運作

目前提供英文工具 (美國)。工具不一定要經過本地化。(日後可能會改變)。

工具的說明文件支援非 ASCII 字元。HTML 和 Markdown 都支援 Unicode (UTF-8) 字元，因此都是說明文件的好選擇。翻譯並非必要，只是可行。

工具若檔案路徑包含二進位序列和空白空間，即可正常運作。使用程式庫處理檔案路徑，而不要將路徑操弄為字串。(例如 path.JOIN 在 Go 中彙整)。

工具可在非英文平台上 (例如日文或法文) 正常運作。 這表示處理二進位檔 (例如 UTF-8) 時，不會損毀。舉例來說，文字檔不是 ASCII 字元。

執行

在執行階段 (或執行時間) 考量工具的行為。

針對無需的工作進行最佳化調整

在適當情況下 (例如使用建構工具)，讓工具在沒有作業需要時快速結束。請盡可能向呼叫端提供依附元件的相關資訊，讓呼叫端準確判斷是否需要呼叫工具。

指令列引數

指令列引數有三種類型：

  • 確切文字
  • 引數
  • 選項 (例如外接切換裝置和按鍵)

完全相符的文字

正確的文字會原封不動地放在指令列中。一段確切文字可能為必填或選填。除非需要剖析確切文字引數才能避免混淆 (也就是為了正確剖析其他引數)。舉例來說，如果 copy 指令接受多個來源和目的地引數，可以使用確切的文字引數來釐清其為何：copy a b c 可能不夠明確，copy a to b c 則可能表示「a」已複製到兩個目的地。

引數

引數類似函式參數或運算單元，用來對應資料。順序通常很重要。在 copy <from> <destination> 範例中，<from> 和 <destination> 都是已排序的引數。如果單一邏輯引數重複，順序可能並不重要，例如，移除 <files>...，工具可能會以任意順序處理 <files>。

選項

部分引數稱為選項。切換鍵和按鍵 (鍵/值組合) 都是選項。選項通常會修改工具的行為或工具處理參數引數的方式。選項是由破折號前置字串字母或字詞所組成。

選項開頭必須是一 (「-」) 或兩個 (「--」) 破折號，後面接著一個英數字元標籤。如果採用單一破折號，則標籤的長度必須為 1。如果標籤長度為 2 個字元以上，則必須使用兩條破折號。 例如：-v 或 --help 是正確的；-help 則無效。

如果是包含多個字詞的選項名稱 (例如「foo bar」)，您必須在字詞之間使用半形破折號 (「-」)。例如，「foo bar」會變成 --foo-bar。

所有選項都必須提供 (--) 選項。您可以選擇提供單一字元簡寫 (-)。舉例來說，您可以只提供 --output，也可以同時提供 -o 和 --output，但如果只提供 -o 選項，就無法提供較長的選項。

請勿建立數字選項，例如 -1 或 -2。例如：新增 --once 選項，而不是讓 -1 表示只執行一次操作。如果需要數字值，請加上鍵/選項，例如 --repeat <number>。

只能有一個 (-) 或兩個 (--) 破折號是特殊情況，且無法用做鍵或切換鈕。

切換按鈕

顯示切換按鈕代表「開啟」的功能，如果沒有，則代表該功能處於「關閉」狀態。將預設值切換為「關閉」。與索引鍵選項不同，切換按鈕不接受值。例如：-v 是常見的外接切換意義，而且不採用值，而是改為切換值，而不是按鍵值。

所有外接切換裝置皆須妥善記錄 (不得隱藏的外接切換裝置)。

系統不允許同時使用外接切換裝置。例如 -xzf 或 -vv，每個值都必須是單獨的：「-x -z -f」或「-v -v」。

鑰匙鍵選項

索引鍵選項是由鍵和值組成。鍵和切換按鍵的語法類似，但有鍵的選項預期金鑰值。舉例來說，-o <my_output_file> 含有「-o」鍵，且值為「my_output_file」。

請勿使用等號 (或類似) 來分隔鍵和值。例如，請勿使用 -o=<my_output_file>。

少數情況請注意：請避免使用選用鍵 (該值不含鍵的鍵) 或選用值 (索引鍵出現時但不含其值的位置)。您可以更清楚地將鍵/值組合視為選用，但可以分離。也就是如果鍵中含有值，反之亦然。建議您建立引數，而非使用選用鍵的索引鍵選項選項。舉例來說，如果不傳遞 [<config_file>] 就不是「do-something [--config [<config_file>]]」，代表不會使用設定檔；而如果傳送 --no-config，則「do-something [--config <config_file>|--no-config]」表示不會載入設定檔。

多款獨家選項

有些選項不適合使用其他選項。我們呼叫這些選項時並非必要。

傳送互斥的選項會視為使用者錯誤。發生這種情況時，工具會執行下列任一操作：

  • 撰寫錯誤訊息，說明問題，並以非零的結果代碼結束；無需工作 (即呼叫並未變更資料)。這是預期的處理方式，因此不需要提供進一步的說明文件或附註。
  • 優先採用其中一個選項。例如「passing -z will override -y」。在這種情況下，處理作業會記錄在 --help 輸出內容中。
  • 其他處理方式可能 (優先優先或最後優先處理或其他事項)，但我們不建議這麼做。在這種情況下，處理作業會在「說明」、「選項」和「附註」中記錄；但在「說明」和「選項」中，則可在 Notes 中使用「See Notes」進行完整寫入。
分組選項

目前沒有特定的語法來表示啟用選項時也會影響其他選項。如果選項暗示其他選項已啟用或停用，請在「選項」中加以指定。例如，「passing -e implies -f」表示如果啟用 -e，-f 就會像在指令列上傳遞一樣啟用 (無論 -f 是否已明確傳遞)。多餘傳遞隱含值不會造成傷害 (並非錯誤)。

選項分隔符號

兩個破折號 (「--」) 各自代表引數選項的結束。後續的所有值都會依原樣提供給工具。例如，使用「Usage: foo [-a] <file>」時，指令列「foo -- -a」可能會將 -a 解讀為檔案名稱，而非切換鈕。此外，「foo -a -- -a」會啟用切換按鈕 -a (-- 前的第一個 -a)，並傳遞常值文字 -a (第二個 -a)。

重複選項

重複的外接切換裝置可用於套用更多強調效果 (但強調的意思是工具，此處的說明刻意模糊不清)。常見的例子是傳遞更多 -v 切換按鈕來提高詳細程度。

使用重複鍵的選項可用於將多個值傳送至同一個指令。這樣做通常是為了避免多次呼叫同一個指令。可接受重複選項的常見指令為 cp、rm、cat。請務必小心，確保重複的指令不明確且清晰。例如，cp 一律會將最後一個引數解讀為目的地。如果 cp 接受多個來源和目的地引數，剖析就會產生模稜兩可或不清楚的情形。

標準輸入別名

在 Fuchsia 工具中，單破折號 (-) 不會解讀為 stdin 的別名。您可以使用管道引導資料至 stdin，或使用 /dev/stdin 做為 stdin 的別名。(注意：/dev/stdin 不適用於 Fuchsia 和 Windows)。

單破折號

只保留一個破折號 (「-」)，保留供日後使用。

子指令

工具可能包含接受獨立指令列引數的子指令。(與 git 工具類似)。子指令開頭不得為破折號。例如，在 fx build 中，build 引數是子指令。

當工具有多個子指令時，也應該包含說明子指令，以顯示其他子指令的說明。例如，「fx help build」將提供建構子指令的相關說明。

子指令可能有各自的引數，且主要工具不會處理。工具名稱與子指令之間的引數是由工具和子指令的引數處理，在子指令後方的引數則會由子指令處理。例如，在 fx -a build -b 中，-a 是 fx 工具的引數，而 -b 引數是由 build 子指令處理。

常見功能

指令列工具預計可支援部分常見的外接切換裝置：

  • --help
  • --quiet
  • --verbose
  • --version

互動式說明 (--help)

工具必須接受 --help 切換開關，在此情況下，請將使用資訊提供給指令列。如要瞭解說明文字的版面配置和語法，請參閱 CLI 工具說明需求。

工具在顯示說明時不得執行其他作業 (例如附帶副作用)。

使用可剖析引數及顯示相同來源的說明資訊的程式庫。這樣做可讓兩者保持同步。例如，避免將指令列說明當成獨立文字段落撰寫。

互動式說明應簡潔有力。為經驗豐富的讀者做好準備，例如有人想收到提醒，瞭解如何使用這項工具，或是閱讀互動式說明的某位開發人員。如果你是新手，請提供附註，引導他們參閱 Markdown 說明文件。

提供產生機器可剖析輸出內容的選項。

詳細程度 (--quiet 和 --verbose)

--quiet 和 --verbose 會減少或增加對使用者的輸出資訊。它們為選用項目，但所有工具都會接受它們做為引數，且不得將這些字詞用於其他用途，例如請勿使用 --quiet 關閉音訊輸出 (使用 --silence 或 --volume 0 或其他同義詞)。

互動版本 (--version)

工具必須接受 --version 切換按鈕，並指出在此情況下用於建構工具的程式碼。未指定版面配置和語法，但版本會包含一些類型的版本號碼。

工具回報版本時不得執行其他作業 (含副作用)。

記錄

記錄與一般輸出不同。記錄目標對象通常是工具開發人員或想要偵錯問題的進階使用者。在特殊情況下 (例如要求 --verbose 輸出)，記錄功能可能會進入 stdout。

多個執行緒的記錄不會在一行中交錯單行，也就是說，最小輸出單位為完整的文字行。每一行的前置字串都表示該線條的嚴重性。嚴重性為下列其中一個項目：詳細資料、資訊、警告、錯誤、嚴重錯誤。

指標

每個工具都必須提交隱私權設計文件 (PDD)，才能收集用量指標。

指標是製定品質和業務決策的關鍵。我們需要透過指標解答的問題包括：

  • 我們的使用者使用哪一款作業系統？- 因此我們知道 該如何安排各平台優先處理事務的先後順序
  • 他們使用哪些工具？- 因此我們瞭解如何決定各項投資的優先順序，並瞭解目前使用的工作流程
  • 他們使用工具的頻率為何？- 因此我們知道如何決定各項投資的優先順序 以及瞭解目前使用的工作流程
  • 我們的工具是否在野外都當機？頻率為何？- 我們知道如何優先維護工具
  • 他們如何使用工具？- 假設特定工具具備一或多項功能 我們想要瞭解如何優先分配特定工具工作流程

您必須慎選要收集的指標類型和內容。我們會進行 Google 標準 PDD 審查程序，確保我們遵守 Google 的做法和政策。工具在收集資料前，必須先經過核准才能收集到哪些指標。

設定和環境

工具通常需要瞭解所執行的情境資訊。讓我們看看應如何收集或儲存該內容。

閱讀資訊

工具不應嘗試直接從環境收集或擷取設定或其他狀態。系統會從平台的獨立來源收集附加目標的 IP 位址、建構產品的輸出目錄，或寫入暫存檔案的目錄等資訊。將執行平台特定工作的程式碼分隔開來，可讓工具在不同的平台之間保持可攜性。

在實際可行情況下，設定資訊的儲存方式應以主機使用者熟悉的方式儲存 (例如在 Windows 上使用註冊資料庫)。工具應從 SDK 檔案或平台專屬工具收集資訊，這些工具會封裝從 Windows 登錄、Linux 環境或 Mac 設定讀取工作。

我們也將不偏誤的工具，當做任何建構系統或環境。您可以存取通用檔案，例如建構輸入依附元件檔案。

寫入資訊

除非工具明確用於修改環境的預期部分，否則工具不會修改設定或環境設定。

如果修改工具一般範圍以外的環境可能對使用者有幫助，則工具可能會在獲得使用者的明確權限的情況下嘗試。

執行成功和失敗

指令列工具離開時，系統會傳回 [0..127] 範圍中的整數值。 0 表示成功 (無錯誤) 和 1-127 表示錯誤形式。值 1 會用於一般錯誤。除了 0 和 1 以外的任何值，都必須為使用者記錄。

讓 Grace 助你一臂之力

如果沒有發生任何錯誤，請傳回結果代碼為零。

避免在成功時產生不必要的輸出內容。請勿顯示「Succeeded」(除非使用者要求詳細輸出)。

如有任何疑問，請停止

如果工具遇到模稜兩可的情況，或是有資料損毀的風險，請勿繼續。例如，如果您要求刪除的目錄路徑恢復為「/」，則可能在嘗試取得該設定資訊時發生錯誤，避免「正在銷售」，並移除「/」下的所有內容。

保持不失敗

工具必須傳回非零的錯誤代碼，清楚指出失敗。如果可行 (如果適合工具使用，或使用者明確要求提供詳細輸出內容)，系統會列印錯誤訊息，說明發生錯誤的原因。

失敗時提供指示

當工具執行失敗時，您必須清楚說明錯誤是來自錯誤的輸入、缺少依附元件，或工具中的錯誤。請讓錯誤報告一目瞭然，方便您採取行動。

如果錯誤來自錯誤輸入內容

  1. 如果使用者提供工具錯誤資料，請提供錯誤的相關資訊，並引導使用者修正輸入內容，例如輸出發生輸入錯誤的輸入檔案 (如有需要，也可使用行數)。
    • 偏好採用下列格式的輸出內容 (方便使用規則運算式)：file_name:line:column:description。這是許多工具的常用格式。其他格式也可使用，但建議您使用方便人類和工具剖析的工具。
  2. 提供進一步資訊的參考資料。如果有相關說明文件，請提供工具的一般說明文件連結，或特定錯誤的說明文件。如果工具有提供更多詳細資料的容量，請描述相關資訊 (例如 gn 如何說明如何執行工具來取得進一步協助)。

如果錯誤來自缺少依附元件

  1. 請清楚說明錯誤是否缺少依附元件。請勿讓使用者嘗試對輸入資料進行偵錯，如果不是問題所在，
  2. 提供如何滿足依附元件的操作說明。這可以是執行的範例指令 (apt-get install foo)，或詳細操作說明的連結 (see: http:example.com/how-to-install-foo)。

如果錯誤來自工具中的非預期狀態 (例如錯誤)

  1. 道歉。說明工具進入非預期的狀態。請勿讓使用者嘗試猜測其輸入資料是否錯誤，或缺少依附元件。
  2. 建議提供郵寄清單或論壇以取得協助。請協助使用者瞭解下一個工具版本中的錯誤是否已修正，或已有人找到解決方法。
  3. 邀請使用者輸入錯誤報告，並盡可能簡化相關資訊。提供指向錯誤資料庫的連結，並預先填入工具和平台資訊。

包含測試

工具必須包含測試，確保其行為正確無誤。每項工具都包含單元測試和整合測試。測試會在 Fuchsia 持續整合中執行。

印尼盾

由於 IDK 機器人目前並不會阻止破壞性變更，因此從 Fuchsia 版本 (pm 等) 匯入的 IDK 工具會在 Fuchsia 持續整合中執行測試。

ffx ffx 平台提供一個架構，用於導入在 Fuchsia 持續整合中自動執行的測試。協作者可以查看 ffx 來源中的外掛程式測試和端對端自我測試示例。

說明文件

Markdown 說明文件是提供更詳細的使用範例與說明的地方。

印尼盾

凡是內含 IDK 且預計由使用者直接執行的工具，都必須有對應的 Markdown 說明文件檔案。

使用者和程式輔助互動

這項工具可以由真人使用者以互動方式執行，也能透過指令碼 (或其他工具) 以程式輔助方式執行。

雖然每項工具都會預設為互動式或非互動模式，前提是他們可以正常使用模式，但也必須接受明確指示，在指定模式下執行 (例如：允許使用者執行程式輔助介面，即使是在互動式殼層中執行)。

標準差

若是通常非互動式工具，請避免要求使用者輸入內容，例如朗讀行文字或線條。請勿突然顯示非預期的提示來詢問使用者問題。

對於提示使用者輸入內容的互動式工具 (例如 zxdb)，這是預期會出現的。

標準輸出

透過 stdout 傳送輸出內容給使用者時，請使用正確的拼寫、文法，並避免使用不尋常的縮寫。如果使用不尋常的縮寫，請確定其在詞彙表中有相關項目。

嘗試檢查終端機是否輸出，即確認使用者是否在當中，或接收端是否為程式。

ANSI 顏色

我們允許使用顏色，但請留意以下注意事項：

  • 隱藏顏色：
    • 請盡可能檢查終端機是否支援顏色，如果不支援，請隱藏色彩輸出。
    • 一律允許使用者手動隱藏色彩輸出，例如使用 --no-color 標記和/或設定 NO_COLOR 環境變數 (no-color.org)。
  • 使用顏色時，請務必針對看不到完整色彩範圍 (例如色盲) 的讀者使用特別的顏色。
  • 切勿只仰賴顏色傳達資訊。請僅使用顏色做為強化效果。不一定需要看見顏色，才能正確解讀輸出內容。

碎石路

使用 stderr 回報無效作業 (診斷輸出)，即工具運作異常時。如果工具的目的是回報問題 (例如 Linter，也就是工具不會失敗的情形)，則將這些結果輸出至 stdout，而非 stderr。

如要進一步瞭解回報錯誤的資訊，請參閱「成功和失敗」一節。

全螢幕

請避免建立全螢幕終端機應用程式。請使用 GUI 應用程式執行這類工具。

非互動式 (程式輔助)

在合理範圍內加入程式輔助介面，以便自動化功能。

如果該網域目前已有通訊協定，請嘗試遵循正確做法 (或給予不要的充分理由)。否則，請考慮使用資訊清單或 JSON 檔案進行機器輸入。

IDE (半程式輔助)

允許整合式開發環境使用工具。通常包括接受資訊清單來輸入及產生資訊清單。

互動 (使用者)

對許多工具來說，在工具執行期間與使用者互動是相當常見的情況。某些工具可透過互動方式執行，例如，rm -i 會在每次移除前提示使用者。

狀態檔案

狀態檔案會編碼資訊，以便在工具間分享資料。PID 檔案和鎖定檔案都是狀態檔案的範例。

避免使用 PID 檔案包含執行中執行檔的程序 ID。

請避免使用鎖定檔案來管理資源存取權的雙向排除設定 (例如互斥鎖)。