Skip navigation

I am quite glad that’s done

A full GitHub year

I technically hit the year mark on January 6 but I wanted a full perfect rectangle of green so I pushed for a week more and this is what I got.

I think it’s time to erm…cash out on the things I learned doing this thing. Or spend more time thinking and less of coding; but I think, the habit can be quite hard to break.

A few more words before I go, the year mostly revolved around two projects, interestingly both a throwback from when I was just fresh out of university.

alexandria is actually a Python “port” of my earliest project on GitHub. Scare quotes on the word “port” because, by now, it hardly is a port. I wonder if the old PHP code will still run if I try to set it up today. The Python port itself, however, was started in 2015.

PyGame-Objects is my earliest attempts at seriously Python-ing. I created Snake this year which is, yeah, not very impressive but it really made me happy to try to write it as cleanly as I could, modifying the framework (which I built too, which is what PyGame Objects is all about) when needed, and maintaining backwards-compatibility with the previous games. I think some time ago (in 2013? But that feels like a lifetime now) I tried to rename it to something cooler but I stuck with the humbler name for now, and for the foreseeable future.

I cannot contain my excitement when the debug mode for PyGame Objects finally worked. Oh what joy! It felt legit even if there is much work to be done.

Pardon my seeming lack of modesty but my great takeaway here is that I write code pretty clean. They say a good rule-of-the-thumb of code cleanliness and documentation is if you can understand code you last touched three months ago. Well I last touched most of PyGame-Objects four years ago!

But I think, I overshot my intended quota of words. Goodbye now. Gotta play The Witcher 3: Wild Hunt.

Don’t Devs Know How to Write?

Back in the day, I was really eager to work with anything you can slap an acronym on. Practice on MVCs, JDBCs, and APIs was sorely lacking in Computer Science at any level, I’d wager, but even more so in undergrad. Heck, How to Design Programs even tiered Scheme such that some library calls and language features are not available for the first several chapters. I felt that this was such a gaping hole in my employability since geeks online develop such strong feelings when an API version is deprecated.

Fortunately, my worries on employability proved baseless. No sooner than my internship did I start working on Android and its API. Then I was into a whirlwind of proprietary MVC and then some networking alphabet soup (hello, TCP, UDP, CIMD2, EMI, SMS, AT codes, ZMQ…whew). And then, in the past few months, some more API here and there. All of which has lead me to the conclusion that documentation—often overlooked, often scoffed at—is incredibly difficult to write, much less understand.

And what would make documentation “good” to begin with? In my opinion, good documentation would be

  1. Friendly to newbies with considerable skill. I add “with considerable skill” because I would not expect any reasonable documentation to start by teaching readers how to program. For a web API, let’s start with a baseline of knowing how to issue GET and POST requests, and maybe parsing JSON. And,
  2. Has a fair amount of short, self-contained, correct examples that anyone on a tight deadline can hack together something reasonably production-ready and that anyone with more time and experience can string together for something fancier. Copy-pastable examples is a huge, huge plus to this point.

(I was sorely tempted to add a sufficient, but not necessary, condition of readers being able to work without referring to StackOverflow but decided against it. Is it really reasonable to expect developers to not refer to StackOverflow, or that they can anticipate a good deal of the unique conditions in which their readers may put their libraries/services/API to use?)

I can name a handful of documents which I think will pass those two criteria. Among them,

  • Android’s documentation.
  • Most, but definitely not all, Python libraries out there.
  • Mozilla Developer Network JS and CSS is something I will find hard to live without.
  • It’s not cool to say this but the Java API docs is definitely above average.
    • And I remember that Sun’s Java tutorial—back when Sun owned Java—is a good jump-off point to the language.
  • Even less cooler to call, is CodeIgniter’s. Anyone remembers CodeIgniter? I’d have to begrudgingly give it to PHP too. Say what you want about PHP as a language but they had usable documentation back when I was actually using it.

I’m trying to come up with a list of those who don’t but I don’t want to name names, especially when documentation is so easy to change1 but, thinking about it, I think I’ve discerned a pattern: they are all, more or less, “corporate data” APIs. And cool companies are not exempt from exposing a “corporate data” API or two.

Common sins of APIs are:

  1. Being outdated. Though I’m inclined to think that frustrations which I’d bin under this label could be due to my slack as well. See I usually just Google-search whatever it is I want to do and work from what seems to be the easiest example to follow from the first page of results. Sometimes, this is StackOverflow so that lets the API writers off the hook. Sometimes, it is really the official documentation. You set things up, copy-paste the code, hit run, see things work through the logs building to that moment of anticipation when the next log should show you the data you are trying to fetch…only for your code to throw an exception. Apparently, in between the time the docs were written and now, they changed the return format of their API without it getting mentioned anywhere.
  2. Not indicating the version for which the docs were written. Slightly related to (1), I stand guilty of this too. Having mentioned my workflow above, when things don’t work, it’s become my habit to check the version for which the docs apply before going to StackOverflow.
  3. Returning unclear error messages. This is a problem that pervades programming in general; at the bare metal, things just either work or not so we created exceptions to distinguish one kind of not-working from another. But even that isn’t perfectly helpful. What do you do when the interpreter tells you it ran into a null pointer in a line of code that has several objects?2 Taken to APIs, sometimes all they tell you is that they ran into a permissions error. But what kind of permission was missing? Was it my API key? Was it permission from the user for our app to access their data? Maybe, permissions error on your OS where your endpoint tried to run a script which not even root has permission to run? Hah, which brings me to the special number in this list which is…
  4. Unnecessarily leaking your implementation to your users. This is special because there is only one (and I hope there will only be one) API I’ve worked with so far which did this. They had other fuck-ups but this is the one which made me question how exactly did my life’s choices lead me to working with them. I know we have a concept of leaky abstractions but asking your API clients to wait for 30s to act on an acknowledgement they received is just sheer incompetence, not an abstraction leaking. Do you even know how to abstract, bro?

Thankfully, if you are working with languages like Python or Javascript, introspection is dead easy which kinda works around the first two. My workarounds for those that fall into #3 has ranged from the obscure (using tcpdump on the connection and debugging on Wireshark) to the fairly standard (excessive logging and StackOverflow searching). As for four…well, thankfully, I was already serving my final 30-day notice when this detail leaked.

To be fair, I’ve had my share of designing a web API for work. I’d admit that there was a phase where our documentation wouldn’t pass my standard3 but when I left I think we were in a state that is, at least, workable, if not passing both my criteria. The title of my post could also be unfair to devs since sufficiently large companies would usually have technical writers who churn out the docs. Having technical writers, however, does not mean that devs have minimal influence on the outcome of the documentation. Based on experience, a technical writer’s job can range from just formatting/proofreading whatever the devs wrote to actually understanding the system they are documenting and actually writing most, if not all, of the documentation.

So, should devs write their own documentation? Why not. The Python libraries that pass my criteria are open-source where, I presume, devs write their own docs. The only problem—at least for most devs—with what I am espousing is that they’d actually have to learn how to write and writing effectively, technical or otherwise, requires empathy. Alas, this would be another blog post on its own.

All that said, I’m at that point in my career when, if asked to work on something you can slap an acronym on, I begin wondering when would Mangastream come around to translating and releasing their Hajime no Ippo backlog. Because best practices, bro, nothing fancy. Best. Practices.

  1. One of the things that came to my mind to call out is Facebook’s docs for setting up a lead gen endpoint. When I was working on it, all they had is a screencast walkthrough of setting up one but then months later, when I had to debug something in my implementation, I found out that they have transcribed the screencast, to my relief. The screencast, being unsearchable to begin with, is definitely not friendly to anyone with a tight deadline (I should know). Whether it is newbie-friendly or not would depend on the newbie’s preference of video over text. [↩]
  2. You reformat your code so that there is only one object per line, heh. [↩]
  3. At the time, the documentation wasn’t solely to blame, I think. The shape of the API then was quite convoluted for a web API that my baseline of knowing GET/POST/JSON would not be enough to work with it. [↩]

Running QUnit Tests Headlessly

Ever since I took it to heart to write unit tests for my code, I’ve wondered how to unit test frontend functionality. Some will say (and this I remember from my early readings on unit testing) that frontend is not meant to be unit tested but, instead, should be end-to-end tested but I respectfully disagree.

(I’d admit though, that I’ve never groked the difference between unit tests and end-to-end tests. They’re all tests to me in that they ensure my implementation is up to spec and that my changes did not break existing functionality. The last part has saved my ass so much for Chess Templar.)

I disagree because frontend code has features that lends itself well to being a unit-testable component. Among them:

  • Creating DOM objects is creating objects. You should be able to assert the properties of the created objects given parameters x and y.
  • Frontend validation. You should be able to assert how your validators behave. All the more true as your validation logic becomes more complicated.
  • It is not uncommon to have a util.js file. These are utilities, possibly used across multiple files and by multiple developers. It better be tested!

Disappointingly, Javascript has remained trapped inside browsers. Sure enough, Node and company are working to do justice on that but the fact remains that not everyone is using Node and company and so their Javascript remain trapped inside browsers.

And it seems that learning how to unit test in Javascript is largely dependent on how you use Javascript. Are you using plain old jQuery? AngularJS, maybe? For my intents and purposes, I’m on plain old jQuery.

It shouldn’t come as a surprise then that I ended up choosing QUnit as my unit testing library. The docs are easy-to-understand enough. With that, you’ll be testing your Javascript in no time!

But then comes the part of automation. The project I am using this for is, quite frankly, small in scope and it would not cost me much neurons to keep in mind to fire up the HTML page of a test-runner I got from reading QUnit’s docs every time I modify my scripts. But a good programmer is a lazy programmer. So I tried to automate that the tests run at Travis as well1.

The easiest guide I can find comes from this StackOverflow answer. The answer assumes an Ant project and the original question is even for Atlassian Bamboo. However, with a few tweaks, I got it to work with the free set-up the internets afford me.

First, you’d have to install xvfb in your environment. Xvfb is crucial for making your tests headless—I’ve actually first encountered it when trying to automate Selenium tests.

What’s fantastic with CIs (done properly) is that your code gets a fresh instance to run on everytime. Though that also means setting up (meticulously) everytime as well; this means ensuring that xvfb and other dependencies like Firefox or a MySQL instance is running before your tests are ran. To do that in Travis, I had the following in my .travis.yml:

language: python
python:
    - "2.7"
before_script: "pip install -r test-requirements.txt"
install: "pip install -r requirements.txt"
script: "nosetests --with-xcoverage && ./run_js_tests"
before_install:
    - sudo apt-get update -qq
    - sudo apt-get install -y xvfb
    - sudo apt-get install -y firefox
    - sudo apt-get install -y mysql-server
    - sudo /etc/init.d/mysql start
    - sudo apt-get install -y mysql-client
    - mysql -uroot -e "CREATE DATABASE alexandria_test;"

Notes:

  • I had to install with the the -y flag. This automatically answers “yes” to all installation-related queries.
  • I had to start mysql manually.
  • I also need to create the test database manually. A few years ago I would be very uncomfortable with the hard-coded test DB name; I would want it to get the name from my config.

Next, we’re using JS Test Driver. There are a couple of Javascript libraries JAR file in the Google Code repo I linked that you need. If you are using git (as I am) and would prefer to submodule, I had the repo ported to git here. I have not yet found the time to submodule since my goal was just to get the set-up working properly.

Having all the required libraries, all the rest are just some configuration. The main call would then be,

java -jar ../lib/JsTestDriver.jar --config jsTestDriver.conf --port 4224 --browser $FIREFOX --tests all --testOutput $OUTPUT_DIR

Where --port is as configured in jsTestDriver.conf and $FIREFOX is the path to the local Firefox installation.

Next come the actual unit tests. If you have followed thus far, you should be able to see some logs related to Javascript tests in your CI server. However, if you followed QUnit’s documentation as it stands (and be able to run your tests from an HTML page test runner), you might notice that your CI reports of 0 tests found and 0 tests ran.

This is because the QUnitAdapter library in JS Test Driver features a different organization than the actual QUnit library. I had to modify my unit tests as in this commit. But in summary:

  • Don’t refer from QUnit. QUnitAdapter provides window-level (read: global) functions that are analogous to QUnit’s. So QUnit.test becomes test and QUnit.module just becomes module.
  • Similarly, forego the asserts. A notable exception is the equality assertion. QUnit’s assert has it as equal while QUnitAdapter has it as equals.
  • beforeEach becomes setup. Self-explanatory.

I figured this out because I read the source code of QUnitTestAdapter. There might be more quirks I haven’t found out yet but these should be enough to get you to testing functionality; the unit test code might not be as idiomatic as desired but hey, it works.

I’m still far from my ideal unit testing set-up for Javascript. All I’ve managed to achieve in this post is to get the tests to run in a CI environment. Notably, test failures for Javascript do not affect the result of the build. I’d also want to get the Javascript included in the coverage reports. And, maybe, reconcile QUnitTestAdapter with the actual constructs of plain QUnit.

  1. Interesting to note that jQuery does not have CI badges on its repo and that they use Node to automate. [↩]

Playing MP3 Files in Java

Following up from my previous post, I have decided to use Java for Museic since, ironically, it looks easier to write platform-portable code that plays MP3 files in Java than in Python. And well it is but that is not to say that the road to my goal was bump-free.

First off, the “default” way to play MP3 files in Java would be to use the JavaFX library. However, JavaFX is not at all available in Java 6 (you need to include specific JARs in your class path to use it), only half-included in Java 7 (you still need to be specific with your class path), and fully-included only in Java 8.

The obvious way to stop worrying at all about the version of Java installed in your system is to use a dependency manager, my choice being Maven. Maven has a JavaFX plugin. All you need to do is (1) fix your class path by issuing the command mvn com.zenjava:javafx-maven-plugin:2.0:fix-classpath and (2) add the following in your pom.xml

<plugin>
    <groupId>com.zenjava</groupId>
    <artifactId>javafx-maven-plugin</artifactId>
    <version>2.0</version>
    <configuration>
        <mainClass>[put your application main class here]</mainClass>
    </configuration>
</plugin>

Alas, I wish it was that easy. In my system, it was complaining about some missing JARs. It seemed to me that I was encountering the very problems I hoped to avoid by using Maven.

Then I realized that I was using OpenJDK 7 instead of Oracle JDK 7. Now, I’m aware of the distinction between OpenJDK and Oracle JDK; at Chikka, we’ve made it a point to use Oracle JDK in production. Nonetheless, for my personal projects, I’ve never experienced any significant difference of OpenJDK so I kept using it as it took less effort to install in Ubuntu. Until now.

The moral of the story is: if you are going to use JavaFX, make sure you are using Oracle JDK.

(And yes, Museic is now playing MP3 files with my desired delay, thank you very much. It’s now my practice/jam buddy!)

Playing MP3 Files Programatically

From my last post, I’m taking a little break from Chess as I turn my attention to a guitar I bought as a Christmas gift to myself. You see, I’m in the process of becoming a Guitar God, ala Jason Mraz, but that story is better reserved for my main blog no?

And well, since I can’t personally jam with Jason Mraz (or Chris Martin), I settle for MP3’s of his songs. The problem is, MP3s play abruptly without warning. There is no sufficient time between my hand pressing play and the song playing!

Jason Mraz Fanboy

And yes, I do have the CDs!

None of the MP3 players I know of is aspiring-musician-friendly as such. So, obviously, this makes it a nice candidate for a quick hack.

My requirements are simple:

  • Have a UI
  • Be able to play an MP3 file after a set countdown. And it has to be in MP3 format, hard requirement. If it is to be of any use with minimal hassles, it has to be MP3.

 

The first requirement makes it a good candidate for a web/JavaScript app. But then, as far as I know, JavaScript is not allowed access to the local filesystem for security purposes. So JavaScript (unfortunately) rules out the more-important requirement of the two I have.

The next obvious choice is Java since I’m quite used to utilizing Swing to develop desktop GUIs; in fact, I created the user interface of our thesis in Swing, from ground up. However, for a quick hack, I think Java might be overkill and there’s this Python library I’ve been wanting to play with for so long…

Kivy!

Kivy can handle my UI requirement, and rather beautifully so, if I may say. Now, searching around, there are multiple ways to play an MP3 file with Python. One of them is even a Kivy library! The other libraries I found are mp3play, musicplayer, and PyGame.

But one by one, problems emerged

  • PyGame’s mp3 support is limited.
  • The sample code in musicplayer’s PyPi page looks too complicated. (Yes, since this is just a quick project, I’m in lazy mode.)
  • mp3play only works for Windows XP.

 

And then the Kivy library. It would’ve been sweet to have a single library for all my project’s requirements. But alas…

Kivy has a SoundLoader class which automagically determines the best way to handle the given sound file’s format. I’m not good with design pattern terminology but, the way I see it, it looks like a combination of Factory and Strategy patterns. However, when I test code given in their documentation, I come across the following logs:

[INFO ] Kivy v1.8.0
[INFO ] [Logger ] Record log in /home/chad/.kivy/logs/kivy_15-01-04_6.txt
[DEBUG ] [Audio ] register SoundPygame
[INFO ] [Audio ] Providers: audio_pygame (audio_pygst, audio_sdl ignored)
[WARNING] [Audio ] Unable to find a loader for <test.mp3>

 

The only provider that loaded is PyGame’s. And, as I’ve noted above, PyGame’s mp3 support is shaky. In fact, Kivy’s code as of presstime only allows PyGame on MP3 files if it is running on Android. audio_pygst would’ve done the trick but then, as the logs indicate, it did not load.

So why did it not load? Looking at audio_pygst’s code, it imports the modules gi, pygst, and gst, in that order, respectively surrounded in try-catch statements should there be problems on the import.

I try to load them manually on Python’s shell and get the following result:

chad@galadriel:kivy$ python
Python 2.7.3 (default, Feb 27 2014, 19:58:35) 
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import gi
>>> import pygst
>>> import gst
/usr/lib/python2.7/dist-packages/gobject/constants.py:24: Warning: g_boxed_type_register_static: assertion `g_type_from_name (name) == 0' failed
  import gobject._gobject
>>>

 

Looking around, this seems to be an issue with gst 0.10.x. The obvious solution would be to upgrade. Unfortunately, gst updates for Ubuntu 12.04LTS seem to have stopped at 0.10.

So there. Much ado achieving nothing, for a quick hack. Maybe, I’ll look into using Java for this project, moving forward. Stay tuned!

Coldplay Fanboy