样式指南

遵循 Google TypeScript 样式指南。

迁移到 TypeScript 和 ES6

Blockly 最初是使用 ES5.1 编写的，符合当时旧版 Google JavaScript 样式指南。新编写的代码应符合当前的样式指南，并使用 ES6 语言功能（例如 let、const、class、重构赋值，如果适用）。现有代码可能会更新，也可能会不合规。Blockly 团队会考虑代码一致性和库用户的体验，尽量做出最佳决策。例如，我们可能会选择不重命名不再符合样式指南的公共函数。

正确做法

  • 使用 lint 和格式设置工具。
    • 我们使用 eslint，并设置了 eslint.config.mjs 文件，其中包含我们首选样式的规则。
    • 我们使用 prettier 进行自动格式设置。
    • 运行 npm run lint 以运行 lint 工具，运行 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;
}