Blockly 樣式指南

遷移至 TypeScript 和 ES6

Blockly 最初是使用 ES5.1 編寫，符合較舊的 Google JavaScript 樣式指南 (當時為最新版本)。新編寫的程式碼應遵循目前的樣式指南，並使用 ES6 語言功能，例如 let、const、class，以及在適用情況下使用結構重組指派。現有程式碼可能會更新，也可能不符合規定。Blockly 團隊敬上考量程式碼一致性和但不要重新命名不再遵守風格指南的公開函式。

正確做法

使用程式碼檢查和格式設定工具。
- 我們使用 eslint 並採用 .eslintrc.js 檔案設定包含偏好樣式的規則
- 我們採用進階自動格式設定功能。
- 執行 npm run lint 來執行 Linter，並針對 npm run format 執行 formatter。
請使用空格 (而非 Tab) 縮排。
請使用分號。
將 camelCase 用於變數和函式。
將 TitleCase 用於類別。
使用 ALL_CAPS 表示常數。
使用大括號適用於所有控制結構
- 例外狀況：您可以省略單行 if 陳述式的大括號。
使用單引號 (撰寫 JSON 時除外)。
在 for 迴圈中重新宣告變數。也就是說，請一律寫入 for (const i = 0; ...)，而非 for (i = 0; ...)。
- 否則，重構後讓變數成為孤立項目，成為一個令人驚訝的全域解釋。
開頭須為大寫英文字母，結尾則須為半形句號。
使用 TODO 建立 GitHub 問題，並使用 TODO(#issueNumber) 建立連結。
使用 TSDoc 為所有內容加上註解。

錯誤做法

使用 Tab 鍵縮排。
在變數或函式名稱的結尾使用底線。
- 某些較早的程式碼會在私人或內部屬性使用底線，或函式。雖然這些程式碼可能會繼續存在，但請勿依照這項慣例新增程式碼。
使用 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;
}