Firefox OS/Comms/Dialer/Design Patterns and Guidelines

Overview

This document serves as a guide for the technical direction of the Gaia Dialer. It is a set of code standards, refactors, and patterns that we will be working towards. It is based heavily on standards and patterns from Gecko. There will be no big push or work done just to align us more with this document. Instead, work will be done incrementally as we work on features and bug fixes. This document is entirely up for discussion. The recommendations in it are based more on a desire for consistency rather than being an assertion that one way of doing things is better than another.

Design Patterns

Class Hierarchy

The pattern that we use is a loose interpretation of Model-view-controller (MVC). We don't think that a total redesign to be true MVC is either beneficial or necessary. We have chosen to focus on the separation of UI and logic code as this is one of our weak areas as of writing. To this end, we have crafted two common hierarchies:

View with subview(s)

--------------------
|   Master---------|---> outside world
|   ^    ^         |
|   |    |         |
|   v    v         |
| UI <--> Handler--|---> outside world
--------------------

(note that UI has no connection to the outside world)
This scenario is the pattern used when there is a master view with subcomponents that function independently. An example of this is the callscreen view and its conference group sub-functionality.
In this scenario, the following are analogous:

• Handler to (Inner) Controller
• UI to View
• Master to (Outer) Model and Controller is this too vague and poorly defined to be useful? this seems to work well for the callscreen

Comments

Classes should clearly delineate the following:

• Their purpose from a high level.
• Their public functions and their parameters.

Example

// ...
/**
 * Manages the view (UI) of the details of an ongoing conference call, this is
 * the presentation of the details of the parties currently participating on it
 * (phone number, contact name, phone number type, etc., if any).
 *
 * The needed HTML code is lazy loaded during initialization in the init()
 * function. It takes care of the initialization automatically.
 *
 * Exposes functions to:
 *  - Add and remove calls to the ongoing conference call details information
 *    overlay.
 *  - Show and hide the ongoing conference call details information overlay.
 *  - Mark the calls participating in an ended conference call as hang up.
 *  - Set the title of the ongoing conference call details information overlay.
 */
var ConferenceGroupUI = (function() {
// ...

Code Style

Code style is largely unstandardized within Gaia.

Long lines

Function calls with callbacks

Function calls that pass in callbacks should wrap to the next line such that the function appears inline with the surroundings, like so:

fooIsAReallyLongFunctionNameThatNeedsWrappingBecauseItIsReallyLong(bar,
function() {
  /* ... */
});

Other sets of parameters

Other large sets of parameters can be wrapped two ways:

fooIsAReallyLongFunctionNameThatNeedsWrapping(someReallyLongBarParam,
                                              'foobarraboof',
                                              moreBar);

or,

fooIsAReallyLongFunctionNameThatNeedsWrapping(
  someReallyLongBarParam, 'foobarraboof', moreBar);

Either is acceptable, but are slightly contextual.

Class Export Pattern

There are two common ways to declare and export classes:

Public 'var' pattern

/* exported Foo */
var Foo = {
};

Exports member pattern

(function(exports) {
  var _foo = {
  };
  exports.Foo = _foo;
})(this);

The former, public 'var' pattern is preferred for the following reasons:

• A /* exported Foo */ declaration is needed to pass jshint, which allows readers to see at a glance what class this file is exporting.
• It is more intuitively obvious what is going on.
• It is less verbose.

Specific Suggestions

ConferenceGroupHandler

ConferenceGroupHandler should be split into ConferenceGroupHandler and ConferenceGroupUI. Code should be taken from CallScreen' as well as ConferenceGroupHandler to form this new class.

CallLog

CallLog should be split into CallLogHandler, CallLogItem, and CallLogUI.

CallLogDBManager

CallLogDBManager should be split into CallLogDBHandler, and CallLogDBItem.

SuggestionBar

SuggestionBar should be split into SuggestionBarHandler, SuggestionBarItem, and SuggestionBarUI.

CallsHandler

CallsHandler should be split into CallsHandler and CallsUI. CallsUI will support the following functionality:

• CallsUI will have an updateButtonState() function that surveys telephony state and updates all CallScreen buttons appropriately.
• CallsHandler.holdOrResumeSingleCall() should be broken up into functional and UI components. Current callsites will call into the CallsHandler function, which will in turn call into CallsUI.updateButtonState().
• CallsHandler.addCall() should be broken up where CallScreen.render() is called. This should be added to a new CallsUI.renderViewForCall() function.
• CallsHandler.handleCallWaiting() should be broken up into functional and UI components. Since most of this function is UI work in nature, the majority of it should move to a new CallsUI.displayCallWaiting().
• CallsHandler.updatePlaceNewCall(), CallsHandler.updateMergeAndOnHoldStatus(), and its supporting function, CallsHandler::isEstablishingCall() should live on CallsUI.