Version 9 (modified by BJ Burg, 8 years ago) (diff)

Organize the various advices, add nits about forEach vs. for..of and forEach this-binding.

These are JavaScript coding styles used in the Source/WebInspectorUI/UserInterface folder.

(Note: Few if any of these guidelines are checked by check-webkit-style. There's a tracking bug for that:

Tokens, spacing, indentation, syntax

  • No trailing whitespace
  • Indent with 4 spaces
  • The opening bracket '{' after a named, non-inlined function goes on the next line. Anywhere else, the opening bracket '{' stays on the same line.
  • Style for object literals is: {key1: value1, key2: value2}.
  • Add new lines before and after different tasks performed in the same function.
  • Calling a constructor with no arguments should have no parenthesis '()'. eg. var map = new Map;
  • Inline anonymous functions, especially if they don't need a bound this-object (using .bind()). Example:
        this.requestRootDOMNode(function(rootNode) {

Naming things

  • Avoid using the "on" prefix where possible. The _onFoo methods can just be _foo or _handleFoo.
  • New class names should use the name of the base class as a suffix. (ex: TimelinesContentView < ContentView). Exceptions: classes extending WebInspector.Object (unless they are a represented object), and deep hierarchies such as DebuggerSidebarPanel < NavigationSidebarPanel < SidebarPanel < Object.
  • Spell out identifier instead of id if not doing so would result in a name ending with capitalized Id. For example, just is fine, but this.breakpointId should be this.breakpointIdentifier.

API preferences

  • Consider using `Map` and `Set` collections instead of plain objects.
  • Consider using rgb() over hex colors in CSS
  • Use for..of syntax when performing small actions on each element. Use forEach when the function body is longer. Use a classical for loop when doing index math.
  • When using forEach or map, supply the this-object as the optional second parameter rather than binding it.

Layering and abstractions

  • Firewall the protocol inside the Manager classes. JSON objects received from the protocol are called "payload" in the code. The payload is usually deconstructed at the Managers level and passes down as smart objects inheriting from WebInspector.Object.
  • Avoid accessing *View classes from *Manager or *Object classes. This is a layering violation that prevents writing tests for models.
  • Avoid storing DOM elements in *Manager or *Object classes. (see above.)

New class skeleton

The new Inspector object classes should have the following format:

WebInspector.NewObjectType = function()

    this._propertyName = ...;

WebInspector.NewObjectType.Event = {
    PropertyWasChanged: "new-object-type-property-was-changed"

WebInspector.NewObjectType.prototype = {
    constructor: WebInspector.NewObjectType,
    __proto__: WebInspector.Object.prototype,

    // Public

    get propertyName()
        return this._propertyName;

    set propertyName(value)
        this._propertyName = value;

    publicMethod: function()
        /* public methods called outside the class */

    // Protected

    handleEvent: function(event)
        /* delegate methods, event handlers, and overrides. */

    // Private

    _privateMethod: function()
        /* private methods are underscore prefixed */