Gaia/System/Refactoring Plan: Difference between revisions

← Older edit

Gaia/System/Refactoring Plan (view source)

Revision as of 13:34, 22 February 2014

1,536 bytes added , 22 February 2014

→‎Stage 1 example

Timdream

Confirmed users

478

edits

@@ Line 13: / Line 13: @@
 === Stage.1 - Painless instantiation ===
-Rewrite all modules to be instantiable and rewrite unit tests, as well as jsdoc. '''Everything that has states need to be an instance, even if we only need one in the app.'''
+'''Everything that has states need to be an instance, even if we only need one in the app.''' Rewrite all modules to be instantiable and rewrite unit tests, as well as JSDOC.
-The stage’s target is to make sure we could have the following pattern:
+See [[Gaia/System/Refactoring_Plan#Stage_1_example|Stage 1 example]] for detail.
-bootstrap.js (starting point, simply one-liner)
+There are already bugs (87 bugs, excluding downloadmananger and fxaccounts for now. Take as you like!) of this stage for every js under the system app. See meta bug.
-<pre>
-// (we need to expose the system instance because test atoms need to call some functions directly)
-window.system = new System();
-</pre>
+==== Initialization ====
-system.js (the "root" of the all modules, starts the "world")
+'''We should not change where we initialize the instance of the module in this stage.''' We do this in Stage 1 to ensure we don't don't need to resolve the launching sequence puzzle for now. If the module your are dealing with simply start itself, feel free to add
 <pre>
-var System = function System() {
+  /**
-  this.appWindowFactory = new AppWindowFactory(this);
+   * Start ourselves
-   this.appWindowManager = new AppWindowManager(this);
+   * XXX: To be moved.
-   this.screenManager = new ScreenManager(this);
+   */
-};
+   window.foo = new Foo();
+   window.foo.start();
-.. prototype methods follows ..
 </pre>
-'''Caveat''': Please take care of instantiation timing and dependency. Please ensure the rewrite does not break anything (run tests!). If you think the parent instance need explicit control over initialization, you may create <code>init()</code> and more some code there.
+at the bottom of the file. If the module is initialized elsewhere, e.g. <code>bootstrap.js</code>, you can still safely do that there.
-With this pattern we are able to do unit test anywhere,
-and there's no architecture design involved in this stage.
-Even a new employee could take one of the modules to rewrite it correctly.
-There are already bugs (87 bugs, excluding downloadmananger and fxaccounts for now. Take as you like!) of this stage for every js under the system app. See meta bug.
+'''Note'''
+* You are required to resolve jshint errors in this stage and remove the file from blacklist.
+* You are required to have unit tests in this stage.
+* If you register any event listener in start(), '''remember to remove them in stop()'''. Otherwise, our unit tests will get confused because we run all unit tests in the same iframe and module dependencies will mess things up. For the self-initialized script, do call the <code>stop()</code> method on the "global" instance in the test <code>setup()</code>.
 === Stage.2 - Architecture love ===
 ==== Find out loading sequence and dependency relationships ====
+. File bugs to track all dependency resolving.
 ==== Do architecture review and rework case by case ====
 # Find the unnecessary module coupling and remove it.
@@ Line 83: / Line 78: @@
 </pre>
 and jsdoc will be generated to 'docs' folder
+=== Stage 1 example ===
+<pre>
+'use strict';
+(function(exports) {
+  /**
+   * DESCRIPTION-OF-THIS-MODULE.
+   * @class Module
+   */
+  function Module() {
+  }
+  Module.prototype = {
+    /**
+     * DESCRIPTION-OF-IMPORTANT-PUBLIC-API
+     * @memberof Module.prototype
+     */
+    show: function(data) {
+      /**
+        * DESCRIPTION-OF-THE-EVENT.
+        * @event Module#i-am-displayed
+        */
+       this.publish('i-am-displayed');
+    },
+    /**
+     * DESCRIPTION-OF-WHAT-START-DO
+     * @memberof Module.prototype
+     */
+    start: function() {
+      if (this._started) {
+        throw 'Module XXX have already started.';
+      }
+      this._started = true;
+      window.addEventListener('someevent', this);
+    },
+    /**
+     * DESCRIPTION-OF-WHAT-STOP-DO
+     * @memberof Module.prototype
+     */
+    stop: function() {
+      if (!this._started) {
+        throw 'Module XXX have not started.';
+      }
+      this._started = false;
+      window.removeEventListener('someevent', this);
+    },
+    /**
+     * DESCRIPTION-OF-EVENT-HANDLER
+     * @memberof Module.prototype
+     */
+    handleEvent: function(evt) {
+    },
+    /**
+     * DESCRIPTION-OF-IMPORTANT-PUBLIC-ATTRIBUTE
+     * @memberof Module.prototype
+     */
+    state: 'begin'
+  };
+  exports.Module = Module;
+}(window));
+</pre>
+[[File:jsdoc-sample.png|300px|thumb|left|Output with default theme]]