Web Blockly Style Guide

TL;DR

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.

Do

  • Use braces for all control structures
  • Indent with spaces, not tabs
  • Use eslint
    • We have a .eslintrc set up with rules for our preferred style
  • Use semicolons;
  • Write code that works in Internet Explorer 10
  • Use underlines at the end of privateVariableNames_ 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
  • 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.

Don't

  • 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 goog.string.startsWith instead.

JSDoc

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

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

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

  • public means that the function or property can be used by outside developers.
  • private means that only the owning class should use the property or call the function.
  • package means that other classes in Blockly may use the property or call the function, but that outside developers may not use it.

Properties

Annotations for properties should include

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

Preferred:

/**
 * 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;

Functions

Annotations for functions should include

  • A description of the function
  • One @param tag per parameter, including
    • Type
    • Name
    • Description
  • A visibility tag: public, package, 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
 */
Blockly.Block.obtain = function(workspace, prototypeName) {
  console.warn('Deprecated call to Blockly.Block.obtain, ' +
               'use workspace.newBlock instead.');
  return workspace.newBlock(prototypeName);
};