DRAFT
Introduction
As we continue to push thin-client interfaces and capabilites, the amount of Javascript we're writing and maintaining has increased substantially. Unfortunately, for most of this expansion we have lacked clear guidelines for Javascript development. This has in part contributed to the fragmentation of our thin-clients into the current collection of various different Javascript frameworks and methodologies. This document is an effort to consolidate best practices and serve as a reference to inform future development.
Javascript Doc
All Javascript should be documented using JSDoc notation https://github.com/jsdoc3/jsdoc. Generation of doc will be added to a future update to Subfloor-JS
AMD and RequireJS
Scripts need to be written as AMD modules. Plenty of documentation exists out on the web. The details of our RequireJS AMD system are described in the link below
RequireJS Javascript loading system in the BA-Server
Unit Testing
MORE RESEARCH REQURED.
Notes: Seems like RequireJS guys have worked around the issues with the major test suites out there, JSTestDriver, Jasmine. https://github.com/jrburke/requirejs/wiki/Test-frameworks
Source maps
Source Maps allow the debugging on compressed and obfuscated javascript by mapping the compressed version to it's original source http://www.thecssninja.com/javascript/source-mapping. GWT, Dojo and RequireJS all support this. Future releases should be constructing source maps for all of the compressed javascript portions of our product.
CSS Considerations
CSS is quickly becoming as much of an issue as the scripts have been. Nothing has been committed to but below are some recommendations to consider going forward.
Pre-processing (compiled CSS)
There's broad interest in moving to a CSS pre-processor to generate consolidated CSS. SASS http://sass-lang.com is the leading candidate to provide this. Much work needs to be done to migrate to a pre-processor but we should be able to start the transition soon.
Image Bundles (Sprites)
SASS and it's associated tool, Compass http://compass-style.org, provide this capability.
Standardize the DOCTYPE
We need to get to HTML4 strict as fast as possible. In addition, we should consider adopting one of the templates out there, HTML5-Shim or Boilerplate.