6.7 时尚指南
优质
小牛编辑
133浏览
2023-12-01
TL;DR
遵循Google JavaScript样式指南。 如果不确定使用哪种样式,请遵循现有代码的样式。 如果样式指南说要使用Internet Explorer 10中不存在的功能,请忽略它。
建议
- 对所有控制结构使用大括号
- 缩进而不是制表符
- 使用eslint
- 我们为.eslintrc设置了首选样式的规则
- 使用分号
- 编写适用于Internet Explorer 10的代码
- 在privateVariableNames_和privateFunctionNames_的末尾使用下划线
- 使用TODO创建GitHub问题,并使用TODO(#issueNumber)链接它们
- 用JSDoc注释一切
- 将camelCase用于变量和函数
- 将TitleCase用于类
- 使用ALL_CAPS作为常量
- 使用单引号(编写JSON时除外)
- 换行符为80个字符,使审核更加容易
- 在包装的行上缩进四个空格
- 如果一行在多个句法级别被打断,则每个级别应在前一行/句法级别上有四个空格缩进
- 以大写字母开头的注释,以句号结尾
- 在for循环中重新声明变量。 也就是说,始终写for(var i = 0; ...)而不是for(i = 0; ...)
- 不这样做会带来风险,即在将函数重构到更高的位置后,变量将被孤立并成为意外的全局变量
不建议
- 用制表符缩进。
- 使用双引号(编写JSON时除外)。
- 使用snake_case。
- 使用ES6。
- 并非在我们支持的所有平台上都实现了它。
- 使用let(兼容性表)。
- 使用const(兼容性表)。
- 在publicVariableNames和publicFunctionNames的末尾使用下划线。
- 使用格式错误的JSDoc。
- 我们的JSDoc将作为文档的一部分自动发布。
- 写入TODO(用户名)。
- 而是使用TODO创建GitHub问题,并使用TODO(#issueNumber)链接它们。
- 使用string.startsWith。
- 它在IE中不存在。 请改用goog.string.startsWith。
JSDoc
Blockly团队使用JSDoc注释我们的代码并生成文档。 我们期望JSDoc用于类的所有属性(私有和公共)以及所有函数。
JSDoc注释必须以/ *开头,以 /结尾,才能正确解析。
块式使用三个可见性标签。 始终使用尽可能受限的范围。
- public 表示功能或属性可以由外部开发人员使用。
- private 意味着只有拥有的类才应使用该属性或调用该函数。
- package 意味着Blockly中的其他类可以使用该属性或调用该函数,但外部开发人员则可以不使用它。
属性
属性注释应包括
- 物业描述
- 方式
- 可见性标签:公共,打包或私有
首选:
/**
* Whether the block may be deleted by the user.
* @type {boolean}
* @private
*/
this.deletable_ = true;
仅当属性的含义显而易见时才允许.
/** @type {boolean} */
this.movable = true;
函数
功能注释应包括
- 功能说明
- 每个参数一个@param标签,包括
- 类型
- 名称
- 描述
- 可见性标签:公共,打包或私有
- @return标记,如果函数将返回一个值,包括
- 类型
- 返回值的描述(如果有)
例如:
/**
* 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
*/
Blockly.Block.obtain = function(workspace, prototypeName) {
console.warn(
'Deprecated call to Blockly.Block.obtain, use workspace.newBlock ' +
'instead.');
return workspace.newBlock(prototypeName);
};