Skip to content

Code quality audit

Jump to bottom Edit New page
haphut edited this page Apr 14, 2015 · 3 revisions

etranger and haphut examined the client code of sujuvuusnavigaattori for quality issues on 2015-01-27. These are our notes on how to improve the software development process:

  1. Dependency management needs to be introduced. Currently all scripts are listed in index.html in a carefully chosen sequence. There are several module formats to choose from but ES6 modules will be standardised soon.

  2. Replace Finnish filenames with English, e.g. "palvelukartta" with "service map". Not all developers understand Finnish.

  3. Modules should be decoupled by introducing some kind of messaging facility, for example Communicating Sequential Processes (CSP).

  4. Dividing the code into modules has to be more consistent and predictable. Interfaces need to be defined. Some suggestions: MapControl for touching the map and Place for autocomplete results, POIs and previously visited addresses.

  5. Code needs to have more separation of concerns, separating network I/O, user interaction and DOM manipulation from logic.

  6. Data types describing the same kind of real world objects or concerns should be uniform when used in event or message passing across all modules. For example LocalRoute.js and OpenTripPlanner results, if used, should be transformed into a uniform format.

  7. Updated on 2015-04-14: Turf uses GeoJSON as the interchange format. All relevant map libraries understand GeoJSON. Perhaps the data format for geometrical and geographical objects should be GeoJSON.

    Data type for all geometry or geography objects could be the one defined by the main map library, i.e. LatLng for Leaflet or Google Maps. That would allow easy visualization if needed and often map libraries have a (small) GIS toolset available, as well. For example the geographic results from OpenTripPlanner are not currently cleanly transformed into LatLngs before handling.

  8. Move as much code into pure functions as possible.

  9. If a function performs several tasks, it should be split into several functions.

  10. Name of the function should contain a verb describing its primary purpose.

  11. Using self-explanatory function names should make comments unnecessary. Comments rot easier than function names.

  12. Code should be checked against using outdated or poorly supported libraries, possibly like jQuery Mobile.

  13. code should avoid using libraries that duplicate functionality, i.e. one library for DOM manipulation.

  14. There should be a uniform mechanism for HTML templating, e.g. Handlebars.js, instead of "HTML as a string" approach. For example see the Leaflet Icon strings in routing.coffee.

  15. Debugging messages should be centralized and configurable without spamming the console logs.

  16. Introduce unit testing and fuzz testing where possible, usually against module interfaces.

  17. Do not pollute the global namespace. Currently for example window.map_dbg is used heavily in several files.

  18. Do not mix classes with a simple function paradigm. Pick object-oriented, functional or some other style and stick to it.

  19. Introduce proper build modes for different targets, including development builds and configurations for different locations, to be chosen at build time. Currently cordova.js is not needed in the web environment. local_config.js is currently commented out in the HTML instead of added at compile-time or baked into the build process.

  20. Make a separate distribution of the app to be used in production environment by third-party developers, e.g. index.html and the directory static deployed in a directory called dist, and reflect that in the documentation.

  21. Consider changing the primary language from CoffeeScript to plain JavaScript to avoid dependency on non-standard or less supported and thus risky flavours of JavaScript. ES6 supports some of the concepts popularized by CoffeeScript and there are transpilers such as 6to5 to use while browsers do not support all the features. Or use a JavaScript flavour that allows for a simple exit strategy back into JavaScript, such as Facebook Flow.

  22. We recommend to design small modules, meaning that having many, loosely coupled special-purpose modules should be preferred to having just a few general-purpose ones, think simplicity and minimalism of UNIX.

  23. Add bundling for the app in a way that allows for several bundles that can be delivered as needed, independent of the code structure. See the video at http://blog.stevensanderson.com/2014/06/11/architecting-large-single-page-applications-with-knockout-js/ at around 38:20.

Some of the sources that inspired the notes:

Add a custom footer
Add a custom sidebar
Clone this wiki locally