It’s not done until you document your code.

I remember the original “Inside Macintosh.” I actually still have the loose-leaf binder version of “Inside Macintosh” that shipped with System v1.

The original Inside Macintosh documented the “Macintosh Toolkit” (the acronym “API” wasn’t in common use then), and, aside from two introductory chapters–one which described the OS and one which documented a sample application–each chapter followed the same formula. The first part of the chapter, consisting of from 1 to a dozen pages, would provide an overview of that toolkit. For example, the “Resource Manager” overview describes what resources are, how resource are important, and how resources are stored on disk. The second part of the chapter would always be “Using the XXX Manager”–giving examples which generally followed the pattern of how you initialized that manager, how to create or manipulate fundamental objects, how to dispose of fundamental objects, and how to shut the manager down. This would consist of the bulk of the chapter. And the end of the chapter would be a summary–generally a summary of the header file for that manager.

It always struck me that such a model was a great way to handle documentation. Start with a 1 to 3 page introduction to whatever fundamental module you are documenting–a “module” consisting of a logical unit of functionality, which could consist of several classes. Then launch into a 20 page document showing how you use that module: how you start it up, how you use the major features, how you configure the major features, how you shut it down. And give snippets of code showing how these are done.

And the summary should point to either the generated JavaDocs or HeaderDoc generated documentation giving the specific calls and specific parameters for each call.

What is interesting about such a model is that it should be fairly easy to write for the technical person creating the toolset: he knows how he wants his class set to be used, so he should be able to craft documentation describing how to use it. For a class which presents a table, for example, the developer has a mental model of how tables are displayed: a delegate or data source is created which responds to certain calls and is attached to the table.

It has always been my opinion that writing code is simply one part of a multi-step process which ultimately results in your code being used. After all, isn’t the whole point of creating code is getting people to use your code? Developers rail against “lusers” who refuse to learn how to use their computers–but I suspect it’s because developers know their fellow developers are more likely to work through the source kit than the average person, and it allows them the excuse not to write the documentation they should write.

Your code isn’t finished until it is well documented. And complaining about people who are confused without good documentation is simply shifting the blame.

Love-hate relationship with reflection, proxy objects and annotations in Java.

I’m finding I have a love-hate relationship with proxy objects, reflection and annotations.

For our project I need to build a module which is capable of serializing our Java objects over JSON. The specifics of our protocol are a little different than most, so I rolled our own parser. No big deal.

But then our requirements on what can be serialized changed; the server team wants to represent the objects passed to me by interface only. So I started playing with using annotations to mark the interfaces and classes that are serialized, and mark how they should be serialized.

It’s convenient: we can declare a class, sprinkle a few annotations in, and call it a day.

Which I love.

The part I hate, however, is that I’ve now, very easily, with just a few lines of code, created a specialized “meta-language” on top of the Java language to handle the serialization code.

And I despise meta-languages with a fiery hatred that could power a thousand suns.

The problem with meta-languages is that they violate the very notion of “discoverability” which is at the heart of code maintenance. No longer can you sort out the functionality of a class or an interface by looking at it’s declaration–now you have to also understand a domain-specific meta-language which alters the behavior of the those classes and interfaces in some hard to understand way.

Yes, I know: the solution to such a thing is documentation, documentation, documentation. I get that. And I certainly plan to spend more time on my documentation than I did adding the annotations in the first place, and putting plenty of references to that documentation in our code.

But there’s the problem: most programmers despise documentation. They think code should be self-documenting. (Which is another way of saying “I’m a damned lazy fool who is too stupid to recognize those shadows on my retinas as fellow co-workers.”) And so we wind up with very strange meta-language components that are impossible to discover doing tricky things that–without proper documentation–is impossible to understand.

ColorPicker

So the designer I work with gives me colors to use in our application as a web hex color specification, and I need to put it into my iPhone application as RGB values in the range [0,1]. Or I need to pick some color, and I pick an H=210° color, but I need to plug in the color into my application as integer RGB values. Or I need to type in [UIColor colorWithRed:xxx green:yyy blue:zzz alpha:1.0], and I’ve got r=110, g=250, b=155.

So out goes the calculator, and a lot of “155 [Enter] 255 [div]” and typing in the first three digits past the decimal place.

I’m a programmer. I can create tools.

So I built ColorPicker, a Macintosh-only program which allows you to set and adjust colors, and copy them in four different ways, so they can be quickly pasted into Mac, Windows or Java code.

Redistribute as you please, hopefully it will be useful to folks.

Fixed a bug in the asn.1 library

Actually, it’s not my fault. I got the following message from Al Jeyapal, pointing out the error of my ways.

From: Al Jeyapal 
To: woody@chaosinmotion.com
Date: Tue, 14 Jul 2009 14:29:36 +1000
Subject: BerUTC Parsing in ASN.1 Library

G'day mate,

I'm not sure if you're still maintaining the code for this library, but
thought I'd send this through in case you are.  There is a slight problem
with how BerUTCTime nodes are created.  The SimpleDateFormat needs to have
it's time zone set explicitly to UTC, else it will interpret the date using
the time zone from the current locale.

Diff is as follows:
@@ -40,6 +40,7 @@
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
+import java.util.TimeZone;

/**
 * Represents a UTC time object.
@@ -98,6 +99,7 @@
    {
        if (gFormat == null) {
            gFormat = new SimpleDateFormat("yyMMddHHmmss");
+            gFormat.setTimeZone(TimeZone.getTimeZone("UTC"));
        }
    }


Cheers,
Al

Fixed in the current build.

Thanks!

Of course I feel stupid: I never noticed the problem before. However, in all of the protocols in all of the places where I’ve used the asn.1 library (and I still use it; I prefer asn.1 data streams to XML in my own ad-hoc protocols), I never had need to use the UTC time.

G’figure.

Java System Property Reference for Mac OS X

I don’t know why I keep misplacing this document, so I’m noting it here for future reference: Java System Property Reference for Mac OS X. This contains the various magic runtime system properties in Mac OS X.

The Java Development Guide for Mac OS X is also useful for how to do certain standard Mac-like things in the Java environment.

What I found was that by testing the System.getProperty(“os.name”).toLowerCase() return string to see if it contains “mac os”, then sprinkle various minor changes to make the UI align with the recommendations in the Java Development Guide above, you can build an application that looks Mac-like on a Mac platform with little effort.

Thoughts on dealing with multiple Activities and UIViewControllers

In a typical model/view/controller implementation (setting aside, of course, the debate over what MVC really is), we implement a model (which maps to a document, file, or database), a controller (which manages the views), and a collection of views, generally contained within a window.

Now this model maps nicely into the iPhone API and the Android API: the basic controller class for the iPhone is UIViewController; for Android it is android.app.Activity. And of course the view hierarchy represents the UIViews and android.view.View objects, both built-in objects and custom objects. The controller object also makes the ideal target for iPhone delegates and data objects and for the various Android interfaces which do essentially the same thing.

On the desktop, most applications are built with either a single model and a single controller. Rarely do we have multiple controllers opened onto the same model, and when this happens, more often than not the multiple controllers are multiple instances of the same class declaration: multiple text editors opened onto the same text file, for example.

Mobile devices are different. On a mobile device you can have a top level screen with one controller drill down to a separate screen (with a separate controller) which displays an individual item, which drills down to a third screen showing information about that individual item, which drills down into a fourth showing the setting for a single field.

In this example, we have four (increasingly fine grained) views into the same model: in the first screen we have a top level view; in the next, a view of an item, and so forth. The original method I was using in order to code for this particular model was to create multiple model-like objects and pass them down to individual view controllers:

Now this model tends to be somewhat informal: my top-level model is (for example) an ArrayList of Items. When it’s time to edit an item, we pass the Item as the sub-model object into the sub-control display. And when it’s time to edit some piece of the Item, we pull that piece out and pass that to the next sub-control display.

The whole process becomes messy for a variety of reasons. First, it creates a strict dependency in the flow of views; even if we use interfaces and protocols in order to isolate a control (and its respective views), we still have a lot of work to do if we want to rearrange views. Second, it creates the problem that we somehow need to pass information about which sub-item was updated back to the previous view controller. This becomes problematic since the events for UIViewController and Activity don’t map well to the notion of “saving” or “marking dirty”: there is no single event we can easily grab that consistently means “You’re going away and the view above you is becoming active.”

Android presents a few twists on this as well. First, when your Android Activity goes into the background it can be deleted from memory in a low-memory situation. That is, you can find yourself in the situation where your Activity goes away and has to be rebuilt from scratch. This implies that you must strictly separate the sub-model from the controller (as opposed to the iPhone, where you can informally combine the model and view controller into the same UIViewController class). Second, well-factored activities can be set up to be brought up by external applications: it is possible your Item editor activity can be brought up by a separate application if it knows how to launch you with the correct Intent.

It strikes me that the proper way to handle this is to have a single unified model, and instead of passing sub-models, we instead pass a small record indicating what part of the model we are working on:

The idea is that the Δ object represents a small record which indicates to the sub-controller which part of the model it is working on. This has the advantage that updates are communicated to each of the controllers which are working on this model as the object updates. This also works well on Android, as individual control/view components can disappear and re-register themselves; the delta record is passed in the Intent which created that component, so when the Activity is reconstructed the Intent can be used to put the view controls back into the correct state.

I have a simple nutrition journal application I’ve been building for the iPhone which I was going to rewrite from the ground up using this model. In future posts I’ll update the post to indicate if this works well or not.