Changes between Version 10 and Version 11 of WebInspectorCodingStyleGuide

Aug 10, 2014 4:32:58 PM (7 years ago)
Brian Burg

i promise to document promises


  • WebInspectorCodingStyleGuide

    v10 v11  
    1010* Style for object literals is: `{key1: value1, key2: value2}`.
    1111* Add new lines before and after different tasks performed in the same function.
     12* Else-blocks and Promise `.then()` blocks should share a line with leading } or }).
    1213* Calling a constructor with no arguments should have no parenthesis `'()'`. eg. `var map = new Map;`
    1314* Inline anonymous functions, especially if they don't need a bound `this`-object (using `.bind()`). Example:
    3839* Avoid accessing *View classes from *Manager or *Object classes. This is a layering violation that prevents writing tests for models.
    3940* Avoid storing DOM elements in *Manager or *Object classes. (see above.)
     41* Avoid using Inspector TypeBuilders outside of InspectorAgent classes. We want to isolate protocol considerations from other functionality in JavaScriptCore and WebCore.
    41 == New class skeleton
     43== Understanding and Using Promises
     45[ What's so great about Promises?] [ The point of promises is to give us back functional composition] and error bubbling in the async world. They do this by saying that your functions should return a promise, which can do one of two things:
     47    Become __fulfilled__ by a **value**
     48    Become __rejected__ with an **exception**
     50And, if you have a correctly implemented `then()` function, then fulfillment and rejection will compose just like their synchronous counterparts, with fulfillments flowing up a compositional chain, but being interrupted at any time by a rejection that is only handled by someone who declares they are ready to handle it.
     52=== Promise Gotchas
     54(Summarized from [ Blog] and [ The Art of Code Blog])
     56* Don't nest promises to perform multiple async operations; instead, chain them or use `Promise.all()`.
     57* Beware of storing or returning promise values that are not from the end of a chain. Each `.then()` returns a new promise value, so return the last promise.
     58* Use `Promise.all()` with `map()` to process an array of asynchronous work in parallel. Use `Promise.all()` with `reduce()` to sequence an array asynchronous work.
     59* If a result may be a promise or an actual value, wrap the value in a promise, e.g., `Promise.resolve(val)`
     60* Use `.catch()` at the end of a chain to perform error handling.
     61* To reject a promise, throw an `Error` instance or call the `reject` callback with an `Error` instance.
     62* A `.catch()` block is considered resolved if it does not re-throw an Error instance. Re-throw if you want to log an error message and allow other parts of a chain (i.e, an API client) to handle an error condition.
     63* Don't directly pass a promise's `resolve` function to Object.addEventListener, as it will leak the promise. Instead, use a single-fire WebInspector.EventListener object defined outside of the promise chain and connect it inside a `.then()` body. Inside the `.catch` block, disconnect the EventListener if necessary.
     65== New class skeleton
    4367The new Inspector object classes should have the following format: