As a pet project that kind of fit into the end-of-year mood, I spent some of my personal time re-releasing my previous code projects. In this post, I will announce the repositories I created and try to document additional works I did on those projects.
The projects are:
- JSZhuyin – “Smart” Chinese Zhuyin IME, extracted from Firefox OS Gaia – previous announcement here.
- Google OAuth 2 Web Client – Browser client OAuth 2 login library for Google accounts, based on previous work in HTML5 Word Cloud
- WordFreq – text corpus calculation, extracted from HTML5 Word Cloud; rewrote substantially.
- wordcloud2.js – word cloud generation on canvas, extracted from HTML5 Word Cloud
All these repositories are created with original commit history. Battling with git filter-branch is quite challenging but fun. I disassemble the work done in HTML5 Word Cloud in order to achieve maximum re-useability; by re-useability, I am also referring to having the code understandable and fixable by others. I’ve already use the Google OAuth 2 Login in an unannounced project and it works great. My goal is to eventually rewrote HTML5 Word Cloud and have it use the libraries from these individual repositories, with slick, better UIs.
These are the things I learned, and implemented:
Coding style, comments, and variable naming
One of the first thing I learned from working in Mozilla is to express thoughts to people, not computers, through code. In fact, in collaborative project like Mozilla, having people understand your code is way more important than having computers run them effectively. To achieve that, code written should be:
- Promote shared understanding through unified coding style. Avoid magical syntax that could confuse the reader.
- Also, promote shared understanding by annotating the work with comments. David Flanagan (Yes, the David) did amazing work in the Gaia code base on this, but sadly we failed to catch up that.
- No secretive variable names; this is particularly rampant in the
wordcloud2.js, and I haven’t been able to fix them all.
Testing and continuous integration
No, I’ve never wrote automatic tests for my projects until this commit. Before that, all the test is done manually by try out the actual product, or on manual test pages.
In WordFreq and Google OAuth 2 Web Client, I (re)wrote QUnit tests for most of the functionalities. The test coverage is not quite there yet, and for Google OAuth 2 library there are no automatic tests in PhantomJS because some tests must be done with a logged-in session.
I’ve also hook up automatic tests of WordFreq to Travis CI. It’s nice to know such service exists that could further reinforce the fork-commit-pull-request contribution cycle on Github. Unfortunately WordFreq fail randomly on the Travis CI testing VM.
Beyond browser context
Javascript does not just live the the browser. With WordFreq, I tried node.js this time. WordFreq is rewritten in a way that it comes with a synchronous interface and a asynchronous interface (powered by Web Workers). With synchronous interface, WordFreq is available as a npm package and is accessible on the command line. node.js is fun, I would love to use it for more stuff and move away from shell scripting. 🙂
Toward a real collaborative open source project
Putting your work on Github is easy, but nurturing that to a solid free software project is hard. You would just need to learn and adopt some software engineering practices besides writing great code, in order to effectively contribute to the free software ecosystems. These are my baby-steps toward that; feedback and contribution welcome!
