程式碼樣式指南

本指南包含為 BeeWare 寫程式碼的資訊和指引。

代碼風格

BeeWare 在程式碼庫中遵循 PEP 8 規範，唯獨行長限制從 79 字元放寬至 88 字元。 我們盡可能使用Ruff來強制執行PEP 8規範。當您提交程式碼時，預提交檢查會執行包括Ruff在內的驗證。在可行情況下，系統將自動格式化您的程式碼以符合我們的格式與風格標準。您可設定某些整合開發環境在儲存時自動執行Ruff，這有助於簡化流程。

請記住，PEP 8 最重要的部分是 第 0 節：愚蠢的一致性是小腦袋的妖精。在某些情況下，與 PEP 8 保持一致是沒有意義的，重要的是要了解，在適用的情況下，寫出不符合所列規則的程式碼是可以接受的，有時甚至是首選。在大多數情況下，知道 * 何時 * 與這些規則不一致 * 與保持一致性同樣重要。

在 API 命名、變數等方面，我們遵循美國的拼寫方式。

應避免的事項

我們儘量避免使用 utils 模組，但也了解到有時這些模組是無法避免的。比較可取的替代方法是在原始碼的其他地方為功能找地方，而不是使用 utils 模組。

一般而言，我們會盡量避免或延遲執行任何耗費資源的初始化程式碼，以實現更快的應用程式啟動速度。例如，toga-core 套件中的模組採用「延遲載入」機制——僅在被請求時才進行匯入，而非預先全部載入。此設計不僅加速啟動流程，更能精準將資源集中於應用程式實際使用的部分。