Blockly 中文文档

# Blockly 风格指南

# 太长不看

遵循 Google JavaScript 样式指南 (opens new window)。新代码应在适用的情况下使用 ES6 语言特性，如let, const, class, 解构赋值等。

# 迁移到 ES6

Blockly 最初是用 ES5.1 编写的，符合旧的当时版本的 Google JavaScript 样式指南 (opens new window)。我们正在将代码库迁移到 ES6 和新样式指南。旧版浏览器，包括 Internet Explorer 11，将继续通过转译为 ES5.1 得到支持。

# 可以

  • 用空格缩进，而不是制表符。
  • 使用eslint (opens new window)。
  • 使用 分号 (opens new window)。
  • protectedVariableNames_在、 privateVariableNames_、protectedFunctionNames_和 的末尾使用下划线privateFunctionNames_。
  • 用于camelCase变量和函数。
  • 用于TitleCase上课。
  • 用于ALL_CAPS常量。
  • 对所有控制结构使用大括号 (opens new window) 。
  • 使用单引号（编写 JSON 时除外）。
  • for在循环中重新声明变量。也就是说，总是写for (let i = 0; ...)而不是for (i = 0; ...).
    • 不这样做会增加在函数中更高层重构后变量将成为孤立变量并成为令人惊讶的全局变量的风险。
  • 在 80 个字符处换行，以便于查看。
  • 用四个空格缩进换行。
    • 如果一行在多个句法级别中断，则每个级别都应从前一行/句法级别缩进四个空格。
  • 注释以大写字母开始，以句点结束。
  • 使用 TODO 创建 GitHub issue 并使用TODO(#issueNumber).
  • 使用 JSDoc (opens new window)注释所有内容。

# 不可以

  • 用制表符缩进。
  • publicVariableNames在和 的末尾使用下划线publicFunctionNames。
  • 使用snake_case.
  • 使用双引号（编写 JSON 时除外）。
  • 使用格式错误的 JSDoc。
    • 我们的 JSDoc 会自动作为文档的一部分发布。
  • 写TODO (username)。
    • 而是使用 TODO 创建 GitHub issue 并使用 TODO(#issueNumber).
  • 使用string.startsWith. 改为使用Blockly.utils.string.startsWith。

# JSDoc

Blockly 团队使用JSDoc (opens new window)来注释我们的代码并生成文档。我们期望 JSDoc 用于类的所有属性和所有函数。

JSDoc 注释必须以开头/**和结尾*/才能正确解析。

Blockly 使用四个可见性标签。始终尽可能使用最受限制的范围。

  • public意味着任何人都可以使用该功能或属性，包括外部开发人员。
  • package表示该函数或属性可以被 Blockly 内部的任何类使用，但外部开发者可能无法使用。
  • protected表示该函数或属性可以被所属类或所属类的子类使用。
  • private表示该函数或属性可以由所属类使用，并且只能由所属类使用。

# 属性

属性注释应包括

首选：

/**
 * Whether the block may be deleted by the user.
 *  @type {boolean}
 *  @private
 */
this.deletable_ = true;

允许，仅当属性的含义很明显时。

/** @type {boolean} */
this.isInFlyout = false;

# 函数

函数注释应包括

例如：

/**
 * Obtain a newly created block.
 * @param {!Blockly.Workspace} workspace The block's workspace.
 * @param {string} prototypeName Name of the language object containing
 *     type-specific functions for this block.
 * @return {!Blockly.Block} The created block.
 * @public * @deprecated December 2015. Will be removed Decmeber 2016. Use
 *     workspace.newBlock instead.
 */
Blockly.Block.obtain = function(workspace, prototypeName) {
  Blockly.utils.deprecation.warn(
    'Connection.prototype.checkType',
    'December 2015',
    'December 2016',
    'workspace.newBlock'
  );
  return workspace.newBlock(prototypeName);
};

← 构建 →