Web Blockly Style Guide


Follow the Google JavaScript style guide. If you are not sure which style to use, follow the style of the existing code. If the style guide says to use a feature that does not exist in Internet Explorer 10, ignore it.


  • Use braces for all control structures.
  • Indent with spaces, not tabs.
  • Use eslint.
  • Use semicolons.
  • Write code that works in Internet Explorer 11.
  • Use underlines at the end of protectedVariableNames, privateVariableNames_, protectedFunctionNames_, and privateFunctionNames_.
  • Create GitHub issues with TODOs and link them using TODO(#issueNumber).
  • Annotate everything with JSDoc.
  • Use camelCase for variables and functions.
  • Use TitleCase for classes.
  • Use ALL_CAPS for constants.
  • Use single quotes (except when writing JSON).
  • Line wrap at 80 characters to make reviewing easier.
  • Indent the wrapped line with four spaces.
    • If a line is broken at multiple syntatic levels, each level should have a four space indent from the previous line / syntactic level.
  • Start comments with capital letters and end them with periods.
  • Redeclare variables in for loops. That is, always write for (var i = 0; ...) instead of for (i = 0; ...).
    • Not doing so raises the risk that after a refactor higher up in the function the variable will be orphaned and become a surprise global.


  • Indent with tabs.
  • Use double quotes (except when writing JSON).
  • Use snake_case.
  • Use ES6.
    • It isn't implemented on all of the platforms that we support.
  • Use let (compatibility table).
  • Use const (compatibility table).
  • Use underlines at the ends of publicVariableNames and publicFunctionNames.
  • Use malformed JSDoc.
    • Our JSDoc is automatically published as part of our documentation.
  • Write TODO (username).
    • Instead create GitHub issues with TODOs and link them using TODO(#issueNumber).
  • Use string.startsWith.
    • It doesn't exist in IE. Use Blockly.utils.string.startsWith instead.


The Blockly team uses JSDoc to annotate our code and generate documentation. We expect JSDoc for all properties of classes, and for all functions.

JSDoc comments must start with /** and end with */ to be parsed correctly.

Blockly uses four visibility tags. Always use the most restricted scope possible.

  • public means that the function or property can be used by anyone, including outside developers.
  • package means that the function or property can be used by any class inside Blockly, but outside developers may not use it.
  • protected means that the function or property can be used by the owning class or subclasses of the owning class.
  • private means that the function or property can be used by the owning class, and only the owning class.


Annotations for properties should include

  • A description of the property
  • The type
  • A visibility tag: public, package, protected, or private


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

Allowed, only when the meaning of the property is obvious.

/** @type {boolean} */
this.movable = true;


Annotations for functions should include

  • A description of the function
  • One @param tag per parameter, including
    • Type
    • Name
    • Description
  • A visibility tag: public, package, protected or private
  • A @return tag if the function will return a value, including
    • Type
    • A description of the returned value, if any

For example:

 * 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) {
      'December 2015',
      'December 2016',
  return workspace.newBlock(prototypeName);