Blockly 樣式指南

遵循 Google TypeScript 樣式指南

遷移至 TypeScript 和 ES6

Blockly 最初是以 ES5.1 編寫,並遵循舊版的 Google JavaScript 樣式指南。新編寫的程式碼應符合目前的樣式指南,並使用 letconstclass 等 ES6 語言功能 (如適用) 解構指派。現有程式碼可能會更新,或可能違反規定。Blockly 團隊會嘗試在考量程式碼一致性和程式庫使用者體驗的情況下做出最適當的決定,例如,我們可能不會重新命名不再遵循樣式指南的公開函式。

正確做法

  • 使用程式碼檢查和格式設定工具。
    • 我們使用 eslint,並針對偏好樣式設定 .eslintrc.js 檔案
    • 我們使用可預先設定來設定自動格式設定。
    • 執行 npm run lint 以執行 Linter,且執行 npm run format 以執行格式設定工具。
  • 以空格縮排,而非定位點。
  • 請使用分號
  • 使用 camelCase 做為變數和函式。
  • 針對類別使用 TitleCase
  • 使用 ALL_CAPS 做為常數。
  • 請針對所有控管結構使用大括號
    • 例外狀況:您可以省略單行 if 陳述式的大括號。
  • 請使用單引號 (編寫 JSON 時除外)。
  • 重新宣告 for 迴圈中的變數。也就是說,請一律寫入 for (const i = 0; ...),而不是 for (i = 0; ...)
    • 否則,在重構函式中較高的位置後,變數會成為孤立狀態,並出現全球出乎意料的風險。
  • 在註解開頭使用大寫字母,並在結尾加上句號。
  • 使用 TODO 建立 GitHub 問題,並使用 TODO(#issueNumber) 建立連結。
  • 使用 TSDoc 為所有項目加上註解。

錯誤做法

  • 以分頁縮排。
  • 請在變數或函式名稱的結尾加上底線。
    • 有些舊版程式碼會針對私人或內部屬性或函式使用底線。雖然這些 API 可能會繼續存在,但您應按照此慣例新增程式碼。
  • 使用 snake_case
  • 請使用雙引號 (編寫 JSON 時除外)。
  • 使用格式錯誤的 TSDoc。
    • 我們的 TSDoc 會自動連同說明文件一併發布。
  • 編寫 TODO (username)
    • 請改為使用 TODO 建立 GitHub 問題,並使用 TODO(#issueNumber) 建立連結。
  • 使用「string.startsWith」。改用 Blockly.utils.string.startsWith

技術支援服務 (TSDoc)

Blockly 團隊使用 TSDoc 為程式碼加上註解,並產生說明文件。我們預期所有類別的公開屬性和所有匯出函式都應使用 TSDoc。

TSDoc 註解的開頭必須是 /**,結尾必須是 */,才能正確剖析。

類型

TSDoc 會略過類型,因為資訊直接位於 TypeScript 程式碼中。如果您要編輯剩餘的 JavaScript 檔案,請按照 Closure Compiler 說明文件加入類型註解。

顯示設定

只能在 Blockly 程式庫中存取的函式或屬性,應加上 @internal 註解。這樣這些屬性就不會出現在公開說明文件中。其他瀏覽權限修飾符應直接在 TypeScript 程式碼中放置 (而非 TSDoc)。

屬性

房源的 TSDoc 應包含屬性的說明。為說明內容,系統可能會省略說明。

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

函式

函式的註解應包含

  • 函式的說明
  • 每個參數一個 @param 標記,包括
    • 名稱
    • 說明
  • 如果函式會傳回值以及傳回值的說明,則標記 @returns

如果函式、參數或回傳值本身很明確,您可以省略說明。

例如:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}