Blockly 样式指南

迁移到 TypeScript 和 ES6

Blockly 最初是用 ES5.1 编写的，符合旧版当前版本的 Google JavaScript 样式指南。新撰写的内容代码应符合当前的样式指南，并使用 ES6 语言功能例如 let、const、class、解构赋值（如果适用）。现有代码可能会更新，也可能会不合规。Blockly 团队会尝试在综合考虑代码一致性和以便为用户提供更好的使用体验 - 例如，我们可能会选择不将公共函数。

正确做法

使用 lint 和格式设置工具。
- 我们使用 eslint，并设置了 .eslintrc.js 文件，其中包含适用于我们首选样式的规则。
- 我们使用 prettier 进行自动格式设置。
- 运行 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 为所有内容添加注释。

错误做法

使用制表符缩进。
在变量或函数名称的末尾使用下划线。
- 某些早期代码会使用下划线来表示私有或内部属性或函数。虽然这些代码可能仍会存在，但不应按照此惯例添加新代码。
使用 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;
}