本頁面將介紹 Starlark 的基本樣式規範，並提供巨集和規則的相關資訊。
Starlark 是一種定義軟體建構方式的語言，因此它同時是程式設計語言和設定語言。
您將使用 Starlark 編寫 BUILD 檔案、巨集和建構規則。巨集和規則基本上是元語言，用於定義 BUILD 檔案的寫入方式。BUILD 檔案的設計重點在於簡單重複。
所有軟體的讀取次數都高於寫入次數。這對客戶來說尤其重要
Starlark，當工程師讀取 BUILD 檔案以瞭解其依附元件的依附元件時
目標和建構作業的細節這種情況通常會在匆忙中或在完成其他工作時發生。因此，簡單易讀非常重要，這樣使用者才能快速剖析及瞭解 BUILD 檔案。
使用者開啟 BUILD 檔案時，會希望快速知道自己在
檔案；或查看該 C++ 程式庫的來源清單。或移除
與該 Java 二進位檔的依附元件每次新增一層抽象化層時
讓使用者難以執行上述工作
BUILD 檔案也會由許多不同的工具進行分析和更新。如果 BUILD 檔案使用抽象項目，工具可能無法編輯該檔案。簡化 BUILD 檔案可讓您取得更優質的工具。隨著程式碼集不斷擴增
更頻繁地變更許多 BUILD 檔案，
更新程式庫或執行清理作業
通用建議
樣式
Python 樣式
如有疑問，請盡可能遵循 PEP 8 樣式指南。請特別使用 4 個空格 (而不是兩個空格) 進行縮排，以遵循 Python 的命名慣例
開始時間
Starlark 不是 Python，
Python 樣式的某些部分並不適用。舉例來說，PEP 8 建議使用 is 比較單例，但 is 並非 Starlark 中的運算子。
Docstring
使用 docstrings 記錄檔案和函式。
在每個 .bzl 檔案頂端使用 docString，並為每個公開檔案使用一個 docstring
函式。
文件規則和切面
規則、面向以及其屬性，以及供應商及其內容
欄位，則應使用 doc 引數記錄。
命名慣例
- 變數和函式名稱使用小寫字母，並以底線 (
[a-z][a-z0-9_]*) 分隔字詞，例如cc_library。 - 頂層私有值會以一個底線開頭。Bazel 會強制執行私人值不得從其他檔案使用。本機變數不應使用底線前置字元。
文行長度
如同 BUILD 檔案中，由於標籤可以長，沒有嚴格的行數限制。
盡可能讓每行最多有 79 個字元 (遵循 Python 的樣式指南 PEP 8)。這項規範不應嚴格執行：編輯器應顯示 80 個以上的欄，自動變更通常會導致行數變長，而人類不應花時間分割可讀取的行。
關鍵字引數
在關鍵字引數中，等號前後的空格會比較使用：
def fct(name, srcs):
filtered_srcs = my_filter(source = srcs)
native.cc_library(
name = name,
srcs = filtered_srcs,
testonly = True,
)
布林值
如要使用布林值 (例如在規則中使用布林屬性)，請優先使用 True 和 False 值 (而非 1 和 0)。
僅將列印功能用於偵錯
請勿在正式版程式碼中使用 print() 函式，因為這項函式僅供偵錯使用，且會向 .bzl 檔案的所有直接和間接使用者傳送垃圾郵件。
只有在已停用的情況下，才可提交使用 print() 的程式碼
而只能透過編輯來源的方式啟用。舉例來說，
使用 print() 會受 if DEBUG: 保護，其中 DEBUG 的硬式編碼為
False。請注意，這些陳述是否足夠實用，以便評估其對可讀性的影響。
巨集
巨集是在載入期間將一或多項規則執行個體化的函式 事實上，Gartner 的資料顯示 只有一半的企業機器學習專案通過前測階段一般來說，請盡量使用規則，而不要使用巨集。建構作業 使用者看到的圖表與 Bazel 在測試期間使用的圖表不同 建構 - 巨集會在 Bazel 執行任何建構圖形分析之前展開。
因此發生問題時
巨集的實作，以排解建構問題。此外，由於結果中顯示的目標來自巨集展開，因此 bazel
query 結果可能難以解讀。最後，任何部分都不會偵測到巨集，因此使用工具
某些切面 (IDE 和其他項目) 可能會失敗。
巨集的安全用途是定義要直接在 Bazel CLI 或 BUILD 檔案中參照的其他目標：在這種情況下，只有這些目標的使用者需要知道這些目標，而巨集引發的任何建構問題都不會與其用途相去甚遠。
用於定義所產生目標的巨集 (巨集的實作詳情) 這些物件不應在 CLI 參照，或取決於目標 沒有由該巨集例項化)，請遵循以下最佳做法：
- 巨集應採用
name引數，並定義該名稱的目標。該目標就會成為該巨集的主要目標。 - 產生的目標 (也就是巨集定義的所有其他目標) 應符合下列條件：
- 名稱前方加上
<name>或_<name>。例如使用name = '%s_bar' % (name)。 - 曝光率受限 (
//visibility:private)，且 - 設定
manual標記，避免萬用字元目標 (:all、...、:*等)。
- 名稱前方加上
name應僅用於擷取巨集定義的目標名稱，不得用於其他用途。舉例來說，請勿使用名稱衍生出非由巨集本身產生的依附元件或輸入檔案。- 您在巨集中建立的所有目標，都應以某種方式 主要目標。
- 巨集中的參數名稱必須一致。如果傳遞參數
做為主要目標的屬性值，請使用相同的名稱。如果巨集
參數的用途與一般規則屬性相同，例如
deps，名稱為屬性的名稱 (如下所示)。 - 呼叫巨集時，請只使用關鍵字引數。這與規則一致，可大幅提升可讀性。
無論是使用原生程式碼在 Bazel 中定義規則，還是在 Starlark 中定義規則，只要相關規則的 Starlark API 不足以滿足特定用途，工程師通常會編寫巨集。如果您遇到這個問題，請詢問規則作者是否能擴充 API 以達成目標。
原則上，與規則相似的巨集越多越好。
另請參閱巨集。
規則
- 規則、層面和相關屬性應使用小寫名稱 (「蛇形大小寫」)。
- 規則名稱是名詞，可從依附元件的角度 (或葉規則的使用者) 說明規則產生的成果類型。不一定是檔案後置字串。舉例來說，產生 C++ 構件 (用於做為 Python 擴充功能) 的規則可能會稱為
py_extension。以大部分語言來說，一般規則包括：*_library- 編譯單元或「模組」。*_binary：產生執行檔或部署單元的目標。*_test：測試目標。這可包含多個測試。*_test目標中的所有測試都應為同一主題的變化版本，例如測試單一程式庫。*_import：目標會封裝預先編譯的構件，例如.jar，或是編譯期間使用的.dll。
- 為屬性使用一致的名稱和類型。部分普遍適用
屬性包括：
srcs：label_list，允許檔案：來源檔案，通常由人編寫。deps：label_list，通常「不」允許檔案：編譯 依附元件data：label_list，允許檔案：資料檔案，例如測試資料等。runtime_deps：label_list：不需要的執行階段依附元件 以便進行編譯
- 如果屬性具有不明顯的行為 (例如含有特殊替換字串範本，或會在特定需求下叫用的工具)，請使用
doc關鍵字引數，為屬性宣告 (attr.label_list()或類似項目) 提供說明文件。 - 規則實作函式在絕大多數的情況下應該都是私人函式
(以底線命名)。常見的樣式是
myrule的實作函式，名為_myrule_impl。 - 使用定義明確的規則，在規則之間傳遞資訊 provider 介面。宣告並記錄提供者欄位。
- 設計規則時，請考量擴充性。提醒您，其他規則 想要與您的規則互動、存取您的供應商，並且重複使用您的規則 您建立的動作
- 遵守規則中的成效指南。