Healthy Code

I work on a team of software developers that maintains several large codebases — too much code for any one person to easily know what’s going on in every part of it at any particular time. I found myself thinking a lot about how to keep the code healthy and a while ago I set my thoughts down as a list of good practices. Thanks to my coworkers at Endless for input, editing, and debate.

The good practices in this post differ slightly from the ones we adopted at work, which reflect the opinions of the whole team; these are worded to reflect my personal opinions.

Assumptions

I don’t like rules without a rationale. I believe these six assumptions underlie the rules that I set out below. That is, if you don’t agree with these assumptions then you probably won’t agree with the rules… ☺︎

  1. We can never know that our own code is correct.
  2. Left unchecked, we will believe our own code to be correct.
  3. Even small mistakes can lead to catastrophic data loss.
  4. Non-trivial programs have interconnections too complex to keep entirely in one person’s mind.
  5. Modifying non-trivial programs will break code unrelated to the modifications.
  6. The business value of maintainable code is only visible to developers.

Good practices for code health

Use your judgement

As always, rules apply only in the absence of any overriding reason to ignore them. Breaking them should be in mutual agreement between the writer of the code and the reviewer. (This system only works if everyone agrees about what the rules are in the first place, though.)

Example reason to break this rule: If no agreement can be reached, then the default is to follow the coding standards.

Review code

Code gets reviewed by a developer who didn’t write any part of it, because of assumptions #1, #2, and #3 — and to spread familiarity with different parts of the codebase throughout the team. Develop with ease of reading in mind, as if you are writing a letter to an unfamiliar code reviewer. Review code skeptically and with full attention, as if it came from a malicious agent out to erase your hard drive.

Example reason to break this rule: You are committing a trivial fix for a broken build and your continuous integration system acts as the code reviewer.

Observe the style

Code follows the coding style. Coding style is important because when code looks the same it’s quicker to read and errors jump out more easily. Apply automated tools when possible to save the code reviewer from becoming a parenthesis counter.

Example reason to break this rule: The code reviewer agrees with you that deviating from the style is more readable.

Test your code

Code needs automated tests. The rationale for this is assumptions #2 and #5, but could be the subject of an entire blog post itself. Lack of tests can be by itself a reason to fail code review, or at least start a dialogue between developer and reviewer about why tests are not necessary in this particular case.

Example reasons to break this rule: A one-off script. A component that proxies an external resource which can’t easily be mocked out.

Refactor on write

You will always have to deal with legacy code (code on which development has ceased but still must be maintained) and rushed code (code which you were forced by circumstances to check in that didn’t quite work well, works but is difficult to maintain, or is not tested.) By assumption #6, you will probably never set aside time to refactor code for its own sake. Therefore, refactor bit by bit to leave the code in a slightly better state each time it’s touched. In this way, code receives refactoring attention roughly proportional to the benefit you receive from refactoring it. If at all possible, add new code with a unit test even if the rest of the code is not written in a testable way.

Example reasons to break this rule: The code is already in good shape. The feature is critical and cannot be delayed. You are contributing your code to an open source project, in which case it is better to work with the upstream community to refactor.

Refactor only on write

Make your diffs per commit no larger than they have to be, in order to make code review easier. Since diffs go line-by-line, do not fix style errors in lines that that are not already being touched in the same commit. Use separate commits if there is an opportunity to make other style fixes.

Example reason to break this rule: If it makes more sense to fix lines other than the ones being edited in one shot (e.g. large sections with wrong indentation), do so throughout the whole file in a separate commit.

Pay down technical debt

Sometimes it’s not possible to build a feature without doing a large refactor first. Determine this as early as possible and include it in the time estimate for the feature. Do not shy away from paying down this debt; it will only compound if you borrow more on top of it. However, keep the changes incremental, and the functionality unimpeded while making these changes.

Example reason to break this rule: Extreme time constraints force you to take out a second mortgage on the code (even then, do this only with a healthy dose of disgust.)

Moving text messages between Android phones

I recently got a new Android phone secondhand, and after resetting it I wanted to move the text message archive over from my old phone. It turns out that you can do this easily if you have root access. Well, technically you can do anything easily if you have root access, but the trick is knowing how. I hope that by putting this out on the internet, other people will be able to know how too.

I had root access on both phones, as they were flashed with CyanogenMod. The new phone is a Nexus 4, and the old phone is an HTC G1 (Android 2.2 is the highest that could run on it.)

On both (and as far as I know, all) versions of Android, all the text messages are stored in this file, which you need root access to read:

/data/data/com.android.providers.telephony/databases/mmssms.db

Getting the file off the G1 was easy; I entered the Terminal Emulator app (I think it’s installed automatically when you flash CyanogenMod) and copied the file to the SD card:

su
cp /data/data/com.android.providers.telephony/databases/mmssms.db /sdcard/

(su requests superuser permissions, which you have to grant.) Then I connected the G1 to my computer with its USB cable and transferred the file off of it.

Getting the file onto the Nexus 4 was harder. What I did not know is that the Nexus 4 can’t mount its SD card as USB Mass Storage (see the explanation), so I ended up using my Apple laptop to do the transfer, and had to download a program called Android File Transfer. Still, I got it onto the phone’s SD card.

Since the newer version of Cyanogenmod comes with a file manager app, I decided to use that to put the file into the correct place, instead of Terminal Emulator (typing shell commands on a phone is no joke.) The file manager is set to “Safe mode” by default which means it won’t request root access. I changed it to “Prompt User mode” in the settings, then navigated to the above databases/ folder and made a backup copy of the old (empty? 100 KB? It’s a sqlite DB so maybe there are still deleted records in there, but I don’t care to check) database. Then I copied the G1’s mmssms.db file over top of it. Unlike on the G1, there was also a mmssms.db-journal file there, which I hoped wouldn’t mess with things…

I couldn’t see my text messages after going into the messaging app, but after rebooting the phone, they were there.

Documentation for GJS

In the last days of January I attended the GNOME Developer Experience hackfest, remotely. This was a first for me since I have not attended a hackfest remotely before. It was also a first for the hackfest, that three remote participants signed up, and we had a discussion on desktop-devel-list as to how that should work.

My main project for the three days was to show people the documentation browser I’ve been working on. This got started a while after last year’s edition of the DX hackfest, which I didn’t attend, but the project was born out of a discussion with some people who were there and talked about it last year.

Some background: You can write applications for the GNOME desktop in many different programming languages, including C, Python, Javascript, and Vala; this is made possible through a piece of software called GObject Introspection, which is a bridge between C libraries and many other programming languages. At (yet another) DX hackfest, the one in 2013, GNOME decided to promote Javascript (and the GJS interpreter, which is basically the Javascript engine from Firefox 24 with GObject Introspection on top) as its preferred platform for application development. Not the exclusive platform, you can still develop apps in Python if you want, but there would be a focus on getting new developers started in Javascript, with tutorials and documentation.

Sadly, since then, we haven’t had good API documentation for developing apps in GJS. The best story we had for a long time was to tell people to refer to the C, Python, or Vala API references and mentally make the transition to Javascript, a process I’ve compared to playing a song on the guitar using chord sheets from the internet, but mentally transposing them to a different key as you go along. At one point, Giovanni Campagna generated some static Javascript documentation and hosted it on his website. This eventually got out of date.

So, this was the problem I was hoping to solve. After a short-lived attempt to write my own web app using Semantic UI (a technology I’d still like to check out someday!) I figured, why bother when there was something that would fit the bill perfectly well: DevDocs, an open-source documentation browser that combines all kinds of documentation from elsewhere (mostly web development technologies) and presents them in a unified fashion with a useful but simple and elegant web app.

In the final quarter of 2015 I worked on this on and off, adding some code to the documentation generator g-ir-doc-tool to make its output suitable for DevDocs to input, and some code to a forked version of DevDocs to import the GNOME documentation and make nice metadata and sidebar entries.

Screenshot of Javascript documentation on DevDocs

Here it is in action

At the hackfest I gave a demo (at 6:30 AM, because of the timezone difference!) to the other people there who were working on developer documentation. I got some good feedback from the people who were listening, discussed some of the shortcomings, and we discussed Mathieu Duponchelle’s new documentation tool, Hotdoc, as well. One good outcome was that the GNOME Developer Center now links to my instance of DevDocs (noting that it’s “experimental”.)

To talk about one of the limitations that we discussed at the hackfest: The approach I chose generates all the documentation from one file, the “GIR file,” which is the same approach that g-ir-doc-tool has always taken. This is nice because it’s self-contained, but also incomplete: API references often include separate pages not connected to any API in particular, such as this one. I think using Hotdoc will help overcome this limitation, since Hotdoc is made for combining these sorts of things. I’m also happy not to work with g-ir-doc-tool since all the stuff I added to it was basically bolted on the side, not really useful for anything else, and therefore not likely to be accepted upstream.

I’m now hosting an instance of the GNOME Javascript API documentation on my modified version of DevDocs: try it out at http://docs.ptomato.name:9292/.

During the hackfest I also collaborated with Philip Withnall on some autoconf macros for GJS and GObject Introspection, which I’ll talk about in a following post…

Some of the other stuff that people worked on is summarized on Philip W.’s blog.

Geek tip: Malloc debugging on OSX

I’ve been trying to chase down an annoying bug that I suspected to be a case of using uninitialized memory. The problem is, it only shows up about 1 in 30 times (I was lucky to notice it in the first place), and never in a debugger.

Fortunately I found that there’s a library on OSX that tweaks malloc() to help you debug:

DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib MallocPreScribble=1 ./myprogram

Or, to do this in LLDB, since due to System Integrity Protection, your linker-affecting environment variables get wiped when you execute a system program:

lldb -- ./myprogram
env DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib
env MallocPreScribble=1
run

This triggered the bug every time, both inside and outside the debugger.

For more information about what you can do with libgmalloc, see this documentation. It only tells how to use that facility in Xcode, though, so the above instructions should help if you’re on the command line.

Endless is Here

For the past 2.5 years I’ve been working at Endless Mobile on something that was mostly secret. You probably caught me being vague about “computers for developing countries.” Well, secret no longer. I am excited, proud, and honestly a bit relieved to be able to say that I can finally tell you what it’s all about.

“Tell you” is a bit of an exaggeration, I’ll let the videomaking skills of my coworker Taylor Morgan show you instead. The video is at the top of our Kickstarter campaign.

We’re launching our first product, via Kickstarter. It’s a computer that’s affordable for people in developing countries, and it looks like this:

Endless One

Alien Egg

I’ve been working on writing applications for this computer, and also contributing to some parts of the operating system. Some parts of this are open source, and you can view them on GitHub.

Also, I have colleagues who are really fun to work with. If you happen to like fun and are looking for a job, there are some positions open… (It’s at the bottom of that page.)

Update: Within only four days, the Kickstarter campaign hit the original goal of US$100 000. It’s incredible. My favorite part is that almost $30 000 of that money was donated by people paying to give a computer, rather than buy one for themselves. Enough people asked for the option to donate a computer directly, so it was added. Also you can now get the whole package for yourself: computer plus swag, because enough people asked for that too.

 

Wave at the camera

You have probably seen the fake advertisement for Wave, the new way of charging your iOS 8 phone in any standard household microwave. (Although I would venture that some of the responses with fried microwaves and phones are hoaxes as well.)

I admit I did giggle when I first read it — some chump microwaved their expensive phone and blew it up, funny, right? Only I realized that it’s not funny at all.

Why shouldn’t people believe that a new technology would allow them to charge their phone by microwaving it? It’s no more or less magical than any other new technology being invented every day. It just happens not to have been invented yet.

Yes, people need to think critically, check sources, use common sense, and become less science-illiterate. Is microwaving your phone a smart thing to do? No. Could the average person probably have known better? Yes. But if you are lucky enough to be in the minority for whom this is obvious, you don’t have any right to laugh at those for whom it is not.

Faster than a speeding bullet

Perhaps not the most wisely chosen title for this Scientific American newsbite, but very cool research: “Ultra High Speed Camera Records at Speed of Light

They have built a high-speed camera with a high-enough frame rate that they were able to watch a pulse of laser light traveling through a Coke bottle in slow motion. (Pause for a moment to watch this video, for it’s really impressive. I’ve linked to the juicy part.)

You should never read Youtube comments, but on this video, people are actually asking good questions, albeit with the usual Internet rudeness. There are two very confusing things said in the video and article which I think are putting people on the wrong track.

Velocity vs. rate

This can’t possibly be true! Nothing can move faster than the speed of light.

The camera does not record at the speed of light (slightly less than 300 000 000 meters per second, or 1 billion km/h). This confuses two common meanings of the word speed: ‘velocity’ and ‘rate’. It makes no sense to say that a camera records film frames at a particular velocity, much less the velocity of light; velocity means something is moving, and in this case nothing is moving fast at all. (Except for the light pulse itself, which of course travels at the velocity of light.)

Instead, by ‘recording speed’, it really means the camera is recording at the rate of 1 billion images per second (which is not the same thing as meters per second). There is a fundamental rule saying that no object can travel at a faster velocity than 300 million meters per second, but there is no such rule for rates.

(Although, if it were an old-fashioned film camera, the film would have to feed through the camera at a velocity faster than the speed of light, which would be impossible. So it’s lucky we live in the digital age.)

“We can see photons”

The other confusing thing is that the researcher says in the video that they can see photons moving through space — that’s strictly true, but not very helpful, since you are seeing photons moving through space right now too. That leads people to ask:

Hey, I thought you could only see light when it reflected off something into your eye! How can we see the photon moving through the bottle when it hasn’t hit anything yet?

Well, the thing we see moving through the bottle is a laser pulse – not one photon but a clump of trillions of them. Out of those trillions, some hit air molecules and fly off in all directions, and some of those happen to hit the camera. We say “the pulse scatters off the air.” So, it’s true, you can’t see photons directly unless they are flying right at you. What we’re actually watching is the air molecules lighting up as the laser pulse passes by.

None of this takes away from the fact that the front edge of that laser pulse travels with the speed of light — and we are watching that in slow motion! How cool is that?