Sort things out: code, project, and open source

Posted on by

This content is over 12 years old. It may be obsolete and may not reflect the current opinion of the author.

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:

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!