Changes between Version 10 and Version 11 of WebInspectorCodingStyleGuide

Timestamp:

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

Author:

Brian Burg

Comment:

i promise to document promises

WebInspectorCodingStyleGuide

@@ -10 +10 @@
 * Style for object literals is: `{key1: value1, key2: value2}`.
 * Add new lines before and after different tasks performed in the same function.
+* Else-blocks and Promise `.then()` blocks should share a line with leading } or }).
 * 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:
@@ -38 +39 @@
 * 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.)
+* Avoid using Inspector TypeBuilders outside of InspectorAgent classes. We want to isolate protocol considerations from other functionality in JavaScriptCore and WebCore.
 
-== New class skeleton 
+== Understanding and Using Promises
+
+[http://blog.parse.com/2013/01/29/whats-so-great-about-javascript-promises/ What's so great about Promises?] [http://domenic.me/2012/10/14/youre-missing-the-point-of-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:
+
+    Become __fulfilled__ by a **value**
+    Become __rejected__ with an **exception**
+
+And, 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.
+
+=== Promise Gotchas
+
+(Summarized from [http://making.change.org/post/69613524472/promises-and-error-handling change.org Blog] and [http://taoofcode.net/promise-anti-patterns/ The Art of Code Blog])
+
+* Don't nest promises to perform multiple async operations; instead, chain them or use `Promise.all()`.
+* 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.
+* 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.
+* If a result may be a promise or an actual value, wrap the value in a promise, e.g., `Promise.resolve(val)`
+* Use `.catch()` at the end of a chain to perform error handling.
+* To reject a promise, throw an `Error` instance or call the `reject` callback with an `Error` instance.
+* 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.
+* 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.
+
+== New class skeleton
 
 The new Inspector object classes should have the following format: