Skip to content

Software Design Guidelines

Jump to bottom
Bruce Schubert edited this page Nov 4, 2018 · 2 revisions

Revisions

Name Date Change Version
Bruce Schubert 2015.07.05 Initial Document 1.0

Contents

[TOC]

Introduction

This document provides insights for developers who want to extend or reuse the Wildfire Management Tool (WMT) web application framework.

Mobile Device Emulation in Chrome

  1. Open the Chrome DevTools: Ctrl+Shift+I.
  2. With Chrome DevTools open, click the >_ icon to open the "Drawer".
  3. Select the Emulation tab at the bottom.
  4. Click the mobile device icon in the top left.
  5. Then select the device model you want to test against in the Emulation tab.

Mix-in Capabilities

You can extend the functionality of World Wind shapes and annotations by simply adding capabilities to them. The Wmt.Globe class has a SelectController that looks for the existence of the following capabilities on the picked object, and it will invoke the appropriate function for the user action:

  • Movable:
  • Openable:
  • Removable:
  • Selectable:
  • ContextSensitive:

Globe

The Globe module encapulates the WorldWindow and its canvas. The Globe extends the WorldWindow by providing terrain data services such as aspect, slope and elevation.

Model-View-Controller (MVC)

The Controller performs services for the views. The Controller owns the Model.

Loosely Coupled

  • Publish/Subscribe pattern

No Globals

WMT does not manifest any globals.

JavaScript Coding Guidelines for WMTweb

This section's guidelines are based for the most part on the Web World Wind Design and Coding Guidelines. The principle differences include JSLint and using NetBeans vs WebStorm for the project IDE.

General

  1. See the WMTweb Software Requirements Specification document for the product requirements.
  2. The project's development IDE is NetBeans. The NetBeans project configuration files for the project define the formatting rules.
  3. The Module pattern is followed for all functionality. All JavaScript code is captured within a module. There is only one global defined by Web World Wind, and that is the WorldWind singleton. It contains the constructors and static functions used throughout the rest of the World Wind library.
  4. http://requirejs.org/docs/api.html is used to support the Module pattern and to provide the Asynchronous Module Definition (AMD). Every module participates in RequireJS/AMD. See: http://requirejs.org/docs/whyamd.html
  5. WMTweb never crashes the browser. Always catch exceptions at least at the highest entry point, e.g., event listeners and thread execution.
  6. Variable and function names are clear, descriptive and easy to read. They are not labelled with a convention not described in this document. Use whole words rather than abbreviations, e.g., "index" rather than "idx". Correct all variable spelling warnings flagged by NetBeans. Add necessary ones to the project's dictionary.
  7. There are no "private" properties or functions/methods in WMTweb . Assume that a module extender will need access to all variables and functions of the module.
  8. Third party libraries are used minimally and strong justification is required for their use. Any usage of third party libraries must be agreed upon among the team and incorporated into the build system.
  9. Within a rendering pass, WMTweb does not access the disk or the network. Disk and network access is done asynchronously.
  10. WMTweb is designed such that the right things just happen once things are set up. The effect of something going wrong is benign. Avoiding micromanagement of state and code brittleness. For example, layers fork off retrieval of data but they don't try to keep track of these retrievals. If the retrieval succeeds then the data will be available the next time the layer looks for it. If it's not available at that point then the layer will simply ask for it again.
  11. All code uses the JavaScript "use strict" directive.
  12. NetBeans flags code errors and warnings as you write it. The errors are indicated by red and yellow markers in the right margin of a module's editor window. When a module is checked in there should be no red flags and all yellow flags should be addressed to the extent possible. Strive to have no warnings or spelling errors. In this case the square at the top of the right margin will be dark green.
  13. The system is designed such that memory allocation and usage is minimized by both the system and its applications. To that end most methods that compute and return a value of type other than Number accept a "result" argument in which to return the computed value. When that argument exists, validate that it is non-null and defined.

Exceptions

  1. Log any exceptions prior to throwing them. Use the same message for the log as for the exception. Use pre-defined logger messages (see WorldWind.Logger) when possible. Pre-define in Logger those messages expected to be used more than a few places.
  2. Ensure all exception messages are descriptive and helpful, but keep them short.
  3. Functions validate their arguments and throw the appropriate exception, typically WorldWind.ArgumentError, and identify the exception message the parameter name and the problem -- null, out of range, etc. Validation is a necessary part of the implementation; code should not be checked in without it.
  4. "Protected" methods whose calling client can't be trusted validate their arguments and throw an appropriate exception.
  5. When validating arguments, do not validate for type. Just validate non-Number arguments for existence and appropriateness to the function. Validate arrays for sufficient length when the necessary length is known a priori.

Code Formatting

  1. All WMTweb code follows the same style and conventions and looks the same in style and format.
  2. WMTweb code is heavily commented. The comments describe both the what and how of a block of code.
  3. WMTweb variable and function names are descriptive.
  4. WMTweb follows the coding conventions described in Chapter 2 of the book JavaScript Patterns. These conventions are encoded in the NetBeans project files.
  5. Line length is 120 characters and indentation widths are 4 characters.
  6. Variable and function names use camel case. The exception is constructors, which capitalize their first letter. Constants are in all upper case with words separated by underscores.
  7. White space is preferred over packing code into a small space. Use white space liberally. Separate functional blocks of code with vertical white space. Think of code within a function as a sequence of paragraphs and separate each with a blank line.
  8. Set up NetBeans to insert the BSD 3-Clause standard license into new code files. The license template can be found in the Downloads section. See Tools > Templates | Settings and edit the User.properties file to set the properties used by the license template. Example:
#!properties
user=<Your Name>
copyright_holder=Bruce Schubert
contact=<bruce@emxsys.com>
organization=Emxsys

Quality

  1. Static code analysis is performed by http://www.jslint.com/help.html.
  2. Run JSLint and address all errors and warnings prior to checking in any code.
  3. JSLint errors and warnings can be viewed in the NetBeans Actions Items window.
  4. Setup NetBeans to use the JSLint plugin. See Tools > Plugins > Available Plugins | JSLint to install, and Tools > Options > Miscellaneous | JSLint to configure. Use the following settings: 1. Assume console, alert, ... 1. Assume a browser 1. Tolerate dangling _ in identifiers 1. Tolerate ++ and -- 1. Tolerate unused parameters 1. Tolerate TODO comments 1. Tolerate messy white space
  5. The only globals that may be defined for a file are: //define// and //$//. Example:
#!javascript
/*global define, $, WorldWind */

Documentation

  1. Documentation is generated by JSDoc.
  2. Run JSDoc and review the results prior to checking in any code. It's a convenient check on documentation and typing.
  3. Document all functions and properties. Mark those meant for internal use only as such.
  4. Code isn't complete until the documentation is written. Write all documentation when you implement the function or property. Don't wait until "later". Assume that you will never return to a module to "clean up".
  5. Use present tense in all documentation. Examples are: "Indicates that ...", "Computes ...", "Returns ...". Do not use terms like "Will compute" or "Will return".
  6. Ensure that the type of all documented arguments and properties is specified in the documentation. For arrays, use {Number[]} and {Vec3[]} and not simply {Array}.
  7. Use correct capitalization and full sentences to document everything. All function, parameter and error descriptions start with an upper case letter and end with a period.
  8. Ensure that all method arguments, return values and exceptions are documented.
  9. Use NetBeans to identify spelling mistakes in documentation. It will flag them with a wavy underline. 1. Class documentation goes in the @classdesc descriptor for the class' constructor.
Clone this wiki locally