Yet I just can’t stay away, and neither can you if you are still reading this.  So let me jump right in with my take…

Ruby Doesn’t Scale.  It can’t take you to the same places Java can.

I don’t mean performance-wise.  And I don’t necessarily believe it can’t scale complexity-wise.  I just think it won’t scale with the size of a team.  I can’t see an application equivalent to 2 million lines of Java code with 80 developers written in Ruby.  Here are some reasons why:

• the language and tools don’t facilitate writing APIs
• it’s too hard to protect code from the side effects of other unrelated subsystems
• the language and tools do not support for components or version management (see my posts on OSGi)
• one bad Ruby developer can do a lot more damage than one bad Java developer
• there are a lot of bad Ruby developers (I am one!)
• the tests don’t scale–no Ruby app can survive inadequate tests, and the while the amount of tests grows linearly with the size of the application, the cost of maintaining them grows exponentially.  This may be true of any tests but…
• you need more tests with Ruby–a Java app can survive without a complete unit test suite.  In fact, some large Java app can survive without tests at all.  Call me crazy but I’ve seen it.  What did we do before JUnit, after all?  I don’t think I’d want to work on one of those apps, but the point is, test code for Ruby is as essential as an interpreter to make a decent sized Ruby app work.
• there’s no meta-programming in Java; that’s kind of a bummer, but it also means no massive indecipherable frameworks collapsing under the weight of the author’s cleverness, frameworks which are so unfathomable they are as brittle as COBOL.

There, I said it.  Now that I did, I’ll make a couple of other observations about why I love Ruby anyway:

• A two million line Java program probably translates to 100K lines of Ruby code
• 80 Java developers are probably as productive as 20 equivalently skilled Ruby developers
• With only a couple of developers, I think there’s no limit to how big the application can be.  In fact, the language is much better suited for a very small team than Java because you can be so much more efficient if you know what you’re doing.
• The tools for Ruby are way behind Java, and there’s no reason to think they won’t catch up.  When they do, it’s entirely possible the gulf between the scalability of the languages will close substantially.  I certainly hope they will.  As far as the tools for writing Ruby go, I feel like I stepped back into 2002 when I went from Java/Eclipse to Ruby/{NetBeans/RadRails/TextMate}.  rake ~ make: when was the last time I typed in make when writing Java apps?
• The tools may be behind, but the available libraries, plugins and gems are already very rich.
• Ruby helped me remember why I love to write programs

The last point I threw in there apropos of nothing, other than to point out that while I do miss some things about writing Java apps, I’m happy to be writing in Ruby now, and hope to keep working on it for the indefinite future, or until our app gets over 100,000 lines of Ruby which should be… never.

P.S. Here’s my favorite entry in the Ruby vs. Java debate, brought to you courtesty of RailsEnvy.

I feel privileged to have worked with Ward in several different contexts, and to have had a front row seat as he developed the first Wiki site and his Framework for Integration Testing (FIT), as well as a few other fascinating smaller projects along the way.  Even though I haven’t worked closely with him over any extended period, in the long run I think I’ve developed a sense of what he’s about as an innovator, and with the publishing of this interview have some reflections on what I’ve learned from him.

Ward to me is a classic idea guy.  He’s always thinking, always saying “what if?”  In many of the conversations we’ve had, I’m embarrassed to say I can hardly keep up.  If I can follow half of what he’s talking about I’m fortunate since that half is usually enough to cause me to go running back to my desk and start working on some new angle in my own work.

Not all of his ideas see the light of day, I’m pretty sure.  But when he hits on a good one, he hits it out of the park–nobody could deny that.  The Wiki wasn’t his first great idea and it definitely wasn’t his last.

So that’s one thing I’ve learned.  Having great ideas isn’t like making great movies, where if you’re Peter Weir you do nothing for five years and then suddenly come out with some brilliant new film, then go quiet again for another five years.  You have to constantly be working on it.  You have to come up with a lot of ideas, be constantly thinking about where to go next, and keep pushing them, trying them out, until you find the one that captures the imagination and the mindset of those around you, and really takes hold.  Put another way, it’s not about the batting average–it’s about the number of at bats.

Joel Spoelsky likes to make fun of smart people, people that say things like,  “spreadsheets are really just a special case of a programming language.”  Rightly so.  Those kinds of smart people are useless.  That’s not Ward.  It’s not enough to just be an idea guy–to always be drawing connections between seemingly unrelated things, or playing with the meaning of things to try to derive new value.  If you want to make your mark the way Ward has, your ideas need to have true value, to make people’s lives easier somehow.  That’s the second thing I learned from Ward.  Great ideas need to be a path to a better way.  The Wiki, XP, and Fit–they all fit the bill in that regard.

Also, Ward’s ideas have a common theme, in my mind.  They are simple but with incredible leverage. He doesn’t overthink anything.  He just starts off with a simple way of looking at something differently.  He challenges conventional thinking, not very overtly, but in a kind of subtle, subversive way, innocently asking, “what if?”

What if customers wrote tests?  (They can’t!)

What if programs told you how they behaved, instead of creating lots tests to ensure they behave how we expect?  (That won’t work!)

What if web surfers could edit the pages they view on the web?  (Chaos!)

Ward knows the most successful systems always start out as simple concepts.  It would be easy to get carried away, to get too ambitious and over-engineer, but he always showed restraint.  The original Wiki, still going strong, is not much changed from the original implementation (although I doubt it is still served over a modem).  Instead, Ward left it to others to explore new platforms, languages, and intentions.  And thus it blossomed.

Which brings me to my third observation on his success.  It reminds me of something my father always used to say: “There is no limit to the amount of good you can do if you don’t care who gets the credit.”  Ward never tried to own the ideas or control them.  He puts everything into the public domain because he feels that’s where ideas can flourish and do the most good.  I believe if he tried to control his ideas with trademarks or patents (some have offered to “help” him by registering Wiki as a trademark), it would have stifled their growth, and maybe we would never have MediaWiki or Wikipedia.

But the best lesson I learned is something I observed when Ward was with other people.  He brings out the best in those around him.  I think he has that effect because he’s such an enjoyable person to be around.  People gravitate towards him.  Humble, unassuming, with not the slightest bit of arrogance, he disarms the cynics and brings people together, getting them to leave egos at the door and get down to the business of talking about really interesting things.  And the best example of that for me is the interview he did with me, which I thoroughly enjoyed.  View it along with the other lightning interviews and I’m sure you’ll see what I mean.

We started out with a large, over-frameworked set of applications built with a creaky buildsystem cobbled together from perl scripts and ant build files. We had all the code crammed into two projects, one for core libraries and the other for application code. The applications were all part of a stack that had a lot of shared libraries and resources and the only thing that kept parts separated were the build scripts which extracted selected packages from the projects and built jars out of them. The jars would then be combined into the classpath for the corresponding application. So there was some attention to keeping components decoupled but nothing that actually enforced dependency management other than the build files. You couldn’t see any real structure emerge by browsing the two projects but after you ran the build you could browse the dozen or so different jar files in the targets directory to identify the common components, the application modules, client libraries for server communication, and the shared open source libraries.

Don’t bother reading that last paragraph again. It’s not worth it. It’s enough to know that things were a mess. We were a long way from a system based on a component architecture with every functional component of the system assigned to a standalone project with it’s dependencies and exports plainly elaborated in the IDE. And even if we did manage to completely reorganize everything, how could it possibly build? Our buildsystem would be useless, and at that moment there were about 25,000 lines of it to contend with.I spent about three weeks doing nothing but analyzing the situation. I didn’t change anything but played around with Equinox. I hacked our jarfiles to make them look like bundles. I wrote some PDE builders to see how they worked. I considered all possible options for breaking apart our two mammoth projects and putting everything back together again in. I read documentation, wikis, blogs and watched a number of EclipseCon presentations. I was already halfway through my alloted time and I had not made one change. Finally I decided to take the plunge. I sent out e-mails to the dev team and told them for the next few weeks (which included the Christmas Holiday) I would be moving code around, breaking the build often, and changing the way they did everything. Then I went to work on a sort of recursive process to break apart the projects and re-constitute them as OSGi bundles.

Here’s how it went:

It’s not hard to make any Java application run in an OSGi runtime. All you have to do is zip everything up into a single file–class files, jar files, resources–and add the appropriate manifest headers. You need to write a few lines of java that implements a bundle Activator by invoking your main() routine. Then you start up your OSGi runtime (Equinox) and have the configuration reference your zip file, which is now a bundle. No application code needs to be changed.

So that was my starting point. I created four different projects for the different applications that made up our product. These projects are OSGi Bundles. I went back to my build output folder from the old ant build and grabbed the jar files needed for each of the applications and copied them into my new bundles. Then I created an Activator class for each one that just called the main() method for the application. I was stunned when it actually worked. It only took a little while but of course I wasn’t actually compiling code. It was just a re-packaging of the binaries.

To get to the point of having all the source in OSGi bundles I was going to have to break down the big bundles into smaller ones and move the source over one at a time. This turned out to be an iterative process that looked something like this:

1. Pick one of the bundle projects I had just created.
2. Go through the jar files inside of it one at a time.For each one, I would create a new bundle corresponding only to that jar file. Let me use utilities.jar as an example. The bundle I created was called com.acme.utilities.
   1. I would take all the classes that appeared in utilities.jar, find the java source files in the old projects and move them into my new com.acme.utilities bundle source folder.
   2. Once I had that working, I would go back through all the other bundles I had already created and find any others that were using the utilities.jar. In those bundles I would delete thejar file and add the dependency on com.acme.utilities.
3. Now my new bundle project had no more jar libraries in it. It also had no source code. I had broken it up into a bunch of bundles like com.acme.utilities so now I could just delete it.

The trick was to work up the food chain starting from the bottom. Pick out the jar files which did not depend on anything else that wasn’t already a bundle. I started with 3rd party libraries and simply converted those jar files into bundles. It only takes a minute to do this in Eclipse or with the excellent BND utility from Peter Kriens. You add the 3rd party bundles to what’s known in Eclipse as the target platform for your application.

After this phase, I had gone from two huge projects to a dozen or so smaller ones, each more clearly identified with it’s function. Instead of one giant “libs” project I had com.acme.utilites.core, com.acme.utilities.swing, and com.acme.utilities.html, etc.

Along the way I discovered problems in our application, like circular dependencies.  These weren’t necessarily bugs but were isolated cases where someone had specifically broken a rule like accessing some view code from the model.  The IDE was catching problems like this.

One lesson I learned was to let go of our classloaders.  We were using classloaders in a number of places to try to scope visibility of jar files or look up classes dynamically by name.  OSGi now managed all of the issues we were trying to solve with classloaders.  Invariably when I encountered places in the code that were passing classloaders as arguments I could pretty much just remove them completely.  OSGi gives you the proper class visibility no matter where you are.When it was all finished I could look at our code and see real structure.  Bundles represented groups of related classes that often corresponded to some layer in the application, like persistence, ui, domain code, messaging, utilities, etc.  Not only could I see the dependencies but I could make strong assertions about them because they were actually being enforced.  I could find exactly who had visibility into classes down to the package level.  The public module APIs were clearly delineated from the implementation classes.  Not only was there loose coupling but there was also good cohesion.

Other unanticipated benefits to developers were immediately apparent:

• It was much easier to understand how things were being used and easier to change them.
• We have an environment that supports different Java VMs in different tiers, but we had to write code to the least common denominator.  Now we could move the major parts of the server to Java5 and utilize things like generics without worrying about breaking other tiers because we had separated out the bundles that were not going into the Java 1.3 applications.
• We didn’t have a 20 minute ant build anymore on the developer desktop.  It was part of the headless build only.  Because the same build artifacts were used to launch apps in the IDE and drive the headless build, they were pretty much in sync with each other so developers didn’t need to do a headless build.  Just edit code, launch application.
• We could create extension points for add-ons, rather than implement complicated hooks with classloaders and convoluted configuration files.  This is part of Equinox, not OSGi per se.  It’s the same kind of benefit you would get with Spring.
• Eclipse was much more responsive.  Apparently having lots of small projects instead of one giant one is more efficient for many tasks.  It didn’t improve Eclipse build times but it did help with other things like auto-complete and refactoring.

There were many, many other nice benefits yielded from this exercise, most of them unanticipated.

Would anyone yield these kinds of benefits from converting to OSGi?  I don’t think so.  We saw such a dramatic improvement because our existing infrastructure was so dilapidated.  Our code was old and the buildsystem brittle.  It’s a common scenario for many Java developers–dealing with the legacy of a system that became massively bloated over time.  We all look at systems like that and wistfully imagine rewriting layers with Hibernate, Spring, Struts, JSF–whatever.  Many times the benefit doesn’t justify the cost, or the rewrite turns into a classic Second System.  From the outset this didn’t seem much different.  Early on I worried this was going to be a very ambitious undertaking, and I had doubts about whether it would spin out of control.

It didn’t turn out like that at all.  In fact, this was my first experience giving a facelift to such an old application with relative ease.  I didn’t have to rewrite any code (other than fixing a few bugs).  I just moved classes around.  I did rewrite the buildsystem, but since the new build artifacts were a tiny fraction of the size of the old buildsystem, this effort paid for itself quickly.   It only took a long time because I was working alone and was being extremely cautious, keeping the system stable continuously throughout the process, rather than just break everything for two weeks and put it all back together again all at once.

Engineers understand the value of this kind of improvement immediately.  You can almost get Product Managers on board with the “SOA in a JVM” story.  But Sales and Marketing won’t bother to stop typing on their Blackberries once you start talking about OSGi.  For me this was mostly about extending the life of a very useful piece of software.  The legacy of older applications isn’t just the code, but all the energy, innovation and hard work that goes into them, regardless of how you feel about the end result.  We owe it to the original authors to make as much as we can of their work.  We’d want nothing less for our legacy.

If my picture wasn’t very clear, or you still don’t fully grasp the motivation for this, I’ll describe a specific example that many Java developers should relate to. But before I do, it might be a good idea to make a more detailed presentation of OSGi and Equinox, the implementation used by Eclipse. Rather than take up space here though, I think I’ll just include some references to articles which I think give the best overview:

This presentation by Jeff McAffer covers some OSGi basics as well as some of the really interesting areas being explored, such as dynamic provisioning of bundles (think of Java Webstart) and API tooling.

• 50 minute presentation by some Equinox implementers introducing OSGi and Equinox. Sample Code available for download.
• Equinox Documentation Page, pretty much all you need.
• Peter Kriens’ OSGi blog (thanks Abhijat!). This covers OSGi in more detail as well as a lot of the politics going on around competing component models.

On a recent project I was working on we ran into a sort of crisis. We had reached a point where development was no longer scaling. Incremental changes to the architecture required a tedious littany of changes to configuration files, build files, test scripts, library paths, IDE configurations, and installer scripts. These changes all had to be carefully coordinated and missed steps often didn’t show up until further downstream; something as simple as adding a new class could result in a ClassNotFoundError in testing if one of the many dependent configurations had not been updated with the new class. So much effort and diligence was required for even small changes that we could not keep up with the kinds of improvements necessary to remain competitive.

We decided to migrate our application runtime to the OSGi Equinox runtime. As it turned out our motivation had nothing to do with the issues above but with other business issues. What we discovered was that after making the investment in structuring our application into bundles, we were able to breathe new life into it. We could again make big changes to the “plumbing” with much less effort and could make stronger assertions about the different parts of the application–what could be safely refactored and what had fragile dependencies.

The improvements included but were not limited to:

• Going from 25,000 lines of ant code required for a full build down to about 200 lines of boilerplate configuration, plus about 200 lines of custom callbacks,
• We eliminated about seventy class file catalogs used to ensure extra classes were not inadvertently shipped in the wrong jar file or duplicated unnecessarily,
• Reducing the size of application distros by eliminating unused dependencies
• Surfacing previously unknown bugs based on dangling references to missing classes and libraries,
• Eliminating a large body of code devoted to managing extensions with segregated class spaces using custom class loaders.
• Going from managing four different runtime configurations for each application–the IDE classpaths, the IDE launchers, the runtime script classpaths, the build script classpaths–down to a single feature descriptor listing the OSGi bundles comprised by each application.

And probably the biggest improvement was in the introduction of the extension mechanism provided in Equinox to extend applications with a sort of dependency injection. This allowed us a new lease on life as a platform for custom configuration and specialized implementations instead of a product trying to be all things to all customers.

The investment required wasn’t trivial but it turned out to be much easier and simpler than I expected. I worked on the conversion myself over a period of weeks. We were able to pull the trigger on the new configuration after about two weeks (implemented over a slow holiday period) and have it fully baked with about a four week effort spread over time. Much of this effort consisted on eliminating the old build system, verifying that everything we did before was being done the same way using the new build system. Developers didn’t really have much downtime but it was very disruptive for them. I had to send out emails every few days or few weeks with instructions on how to do things differently. Most notes were joyous announcements that “you no longer have to” do some tedious routine task that you had to do before. For instance, developers no longer had to kick off an ant build before testing an app. They could launch it directly. They no longer had to update build scripts. We no longer had to wait for the CI server to inform us that a build broke because a dependency was missing. Now Eclipse would show us the missing dependencies. In fact, it did this before but because the configuration of the IDE was separate from the build it wouldn’t really mean anything.

To this day team members still come up to me occasionally to thank me for introducing OSGi, often after being reminded what things were like by having to go back to an old release build. I wish I could take credit but the truth is I never anticipated most of these benefits until I started the conversion.

Now clearly most of the benefit derived had to do with the painfully wrongheaded buildsystem we already had in place by the previous generation of developers. In their defense, it was developed when the only real build tool available was an early version of ant, before they were even using a modern refactoring IDE. And there are a lot of good choices for modern build tools which solve some of these problems (Maven and Buckminster are two that I would look at). But OSGi isn’t really a buildsystem or a configuration management system. It’s simply a runtime that enables solutions to these problems with a much more coherent, consistent and simplified approach.

Our buildsystem, our unit test runner, the IDE, the extensible platform, the launchers, the branding, dependency management–all of these mechanisms are now based on the same set of build artifacts, the Equinox configuration files (bundle manifests, feature and product descriptors), files which are managed with a very nice GUI.

I was expecting to start this entry in early December but I’m learning it’s hard to get a few hours of quiet time at the computer now with the baby and two year old. I’m adapting slowly! I hope to continue the OSGi discussion with the actual procedure for converting applications to OSGi and how the PDE headless build works.

But this appeal isn’t limited to distributed enterprise applications. Wouldn’t software developers like to see a Service Oriented Architecture for the “services” located within a single JVM?

Java Enterprise Software is never written from scratch. Typically it involves writing components that utilize 3rd party libraries, extensions to application frameworks, communications with different tiers. Just look at the class path of any Java Enterprise Application and you’ll see a long list of jar files including JDBC drivers, web application frameworks, validation libraries, Jakarta Commons libraries, and various client libraries. Also, typically you’ll see a number of entries developed by other groups in house: proprietary frameworks, common core utilities, i18n libraries, validation frameworks–on and on.

The end result of the typical class path of a Java application is a giant set of classes from many different libraries all thrown together into a big soup where any class technically can access any other public class, directly or indirectly. Furthermore, nothing guarantees that all the necessary parts are present. Just because everything compiles into jar files doesn’t mean the classes referenced at runtime are actually going to be there, or for that matter be the correct version.

In these applications, dependencies are hard to manage. Tools such as JDepend can be used to identify fragile APIs, problematic dependencies and tight coupling, but nothing really prevents developers from using classes they shouldn’t be using. For instance, once someone uses an Oracle specific class in the Oracle JDBC driver they will be unable to use a different vendor’s driver. Or some code might inadvertently reference an implementation class that is not part of the public API and break on a subsequent upgrade of the library.

Now imagine that the different libraries and frameworks were actually services. They had a public API which is accessible to other components and private implementation classes which are not. The dependencies of any service would be explicit, listing the other services and versions which are required at runtime for them to operate properly. These constraints would be enforced at compilation time as well as at runtime; if a required service in a particular version range is not available in either instance, the system fails fast with an indication of what’s missing. If a service tries to access a public class in a service not listed as a dependency, a class not found error occurs (an error also caught at compilation time). These libraries would still materialize as jar files, but these jar files would be service modules which can be moved in or out of an application even while the application is running. There would be no separate step of composing the classes of a jar file with globs in an ant file. The definition of a service implies the contents of the jar files–no need to maintain an ant file, just a manifest file for the service identifying it’s version and dependencies.

Some of this may already sound familiar. Inversion of Control (IoC) frameworks such as PicoContainer and Spring provide some aspects of the separation of implementation and interface already. Application servers use class loader hierarchies to enforce separation of class visibility within a single JVM. And various application architectural patterns such as Abstract Factories and Dependency Injection provide a means for protecting implementation classes and avoiding fragile APIs.

While these frameworks are all helpful they still leave the programmer in charge of introducing and utilizing them. In most cases, the JVM still loads classes from the big vat of class soup indicated by the class path. What is needed is something more fundamental, something that would completely “invert” the control of the whole application, executing everything as services, not the chosen few components. Instead of the JVM invoking main() on your main class with a single class loader for all your classes, a small application runtime is invoked that looks at all your services, wires up all the dependencies between the services, blocks any that have unresolved dependencies, then invokes start() on each of the services.

Hold it right there, you are probably saying. It already sounds complicated. You might be picturing some big API, or massive documentation you have to go out and read. Sign up for the classes, read the articles, copy the example code, and a week later you’ve got HelloWorld done. Stick with me and you’ll find out it’s not like that. The runtime I’m speaking about is called OSGi and while it is complicated in what it does and how it works, it’s remarkably simple to utilize with the right tool. And more likely than not, you are using that tool already.

OSGi is a standard for a Java component model that has several open source implementations. The most common implementation is calld Equinox. Equinox is the runtime used by the Eclipse IDE and all Eclipse RCP based applications. It’s the lowest level on the Eclipse application runtime stack. It provides the SOA architecture on which Eclipse runs, as of version 3.0. If you’ve programmed RCP applications you’re already familiar with Equinox, but even if you’re just an Eclipse user, you might have noticed that Eclipse is composed of plug-ins which all live in the plugins directory in the Eclipse installation. These plugins are generally jar files or directories that represent the various components of the application. There can be hundreds of these. As an Eclipse user, you may appreciate that you can extend Eclipse with new features by simply adding new plugin jars to the plugins directory and restarting the IDE. If you’ve looked at how Eclipse starts, you’ll see it simply invokes a small jar file on the command line–no reference to any application libraries or classes. As a plugin developer, you are more keenly aware of how these plugins are built, their lifecycle, and the actual mechanics of extending the IDE.

What you may not be aware of is that the plumbing for all of this is not part of the IDE, or even part of RCP, but is actually part of the Equinox runtime bundled with Eclipse. The main class invoked when you start up Eclipse is actually an Equinox entry point, and none of the Equinox code knows anything about Eclipse, RCP, SWT or any of that. This is very important because it means that Equinox can be used as the runtime for any application, including Swing and Web applications.

Eclipse/RCP Architecture built on OSGi

What does all of this mean for you? You have the means and the opportunity to be building your applications with a service oriented architecture, much more easily than you might expect, and I’ve only scratched the surface of the benefits.

You may have noticed it’s been a pretty long gap between my last entry and this one. I’m currently on a leave of absence while managing a new dependency in my family, in the form of a baby boy born on November 14. I’ll pick up this thread in a week or two and show you how we converted our 600,000 line multi-tier swing based application into a service oriented architecture, replacing over 30,000 lines of ant code with about 200 lines, and vastly improving its maintainability and longevity in the process.

Reduce Cognitive Load. This guideline in UI design is about minimizing the amount of things a user has to know in order to be able to use a tool effectively. Likewise, a programmer shouldn’t have to subclass five different classes just to effect one small change to an application. For instance, I often find that in order to add a new behavior interactive application I may have to learn the logging framework, the undo/redo mechanism, the localization framework, and the validation framework–on top of whatever complicated hierarchies exist in the model and views. Things usually reach this state when developers anticipating future needs and striving for reusability and generality in their frameworks end up sacrificing simplicity and, ultimately, usability.

Be consistent. The brake pedal on one model of car shouldn’t serve as the accelerator on another. That would be dangerous. It can also be dangerous to mix thread safe classes with classes that aren’t thread safe, or to have methods accept null String values in some places and throw exceptions in others. If you adopt an idiom in your public interfaces, like converting exceptions thrown by delegate APIs to local exceptions, or using immutable objects as enumerated types instead of ints, then try to stick with it. Consistency fosters a perception of predictability and stability.

…But not too consistent. Jakob Nielsen, a well known usability expert, suggested that you can take certain principles too far, and the principle of consistency is one of those. He felt that Mac interfaces went to excess in trying to maintain consistency, to the point of defying common sense. A famous example: since the operation of removing things from a desktop consisted of dragging them to the trash can, the operation for ejecting a floppy disk was to drag it from the desktop into the trash can, an operation guaranteed to unnerve a user the first time they try it. In software, programmers often step into the realm of over-engineering in an effort to enforce consistency. An action in a user interface may implement an Undoable interface, but that doesn’t mean all actions should be undoable. One might take pains to separate UI code from Domain objects, but if it means introducing intermediary classes and interfaces just to keep domain code from importing javax.swing packages then it may be better to diverge from consistency.

Avoid modality. In many applications users are confronted with modal dialogs which force them to take action before they can proceed in other parts of the application. While a modal dialog is showing, all other parts of the interface are disabled. On the surface this may seem helpful to the user but oftentimes it’s just a convenience for the programmer who doesn’t have the inclination to design the data model so that multiple activities can be conducted concurrently (i.e., changing the properties of an Employee in a dialog while simultaneously deleting that employee in the parent window).

The same thing applies in program design. Sometimes when one object collaborates with another it makes assumptions about the state of that object. Its operation is only guaranteed to be correct under those assumptions. For instance in some data access object there may be operations which result in updating a database object. But these operations might assume that a transaction has been started and fail in the worst possible way if that’s not the case. Users of this class must be aware these methods can only be called in a transaction and keep track of the state of the transaction. An alternative design might encapsulate individual operations in a full transaction, or offer more support keeping track of the transaction state.

Avoid this kind of modality in your classes. You can’t drop all preconditions but the fewer opportunities for failure, the more robust the application.

Utilize Affordances. Affordances are properties of an object that suggest some action can be taken. A door knob “affords” opening a door. A rectangle on a screen may not afford action, but if it is raised and rounded, resembling a button, it affords being pushed. For programmers, affordances might be properties of an interface which make it’s usage more clear. In a class, abstract methods afford overriding. If a class requires several instance variables be initialized when the instance is created, then the programmer should afford that action by adding parameters to the constructor to populate those variables, rather than rely on the caller to invoke setters. Good abstractions and well factored class hierarchies can afford subclass extensions, where flat class structures with duplicate code and concrete classes may not.

Adopt Standards. What more is there to say? Standards in User Interface design result in uniformity across user interfaces, giving the user a sense of familiarity when using an application for the first time. In programming, coding standards provide exactly the same benefit.

Provide Feedback. Feedback in user interfaces usually means giving some indication that a user action has been detected and interpreted. If the action was accepted then give an indication to the user of success. If the action results in an error, make that error known to the user directly. This could probably be interpreted several ways in the context of programming, but the best one would probably be the principal of “Fail Fast.” This means detecting an erroneous use of a class or method early and communicating the actual offense, preferably in a runtime exception, as opposed to letting it go and waiting until the effects of the error cause secondary exceptions which may not reveal the actual API violation. An example of this would be not checking for null values in method parameters but passing the null values on to subsequent calls until a NullPointerException appears in a lower level method. I don’t think you want to check every pre-condition to an exception since it makes methods very noisy, but a lot of times there are conditions which are more likely to be violated. Play the odds and enforce those when you come across them.

You can really go on and on with this idea. The principles of usability apply to any system that interacts with a user, and that includes a programming model. The goal of a great programmer should be the same as the great product designers: empower and delight your users. Programmers should never forget that ultimately their users are not CPUs but other programmers.

The idea of applying Human Factors to API design is not far off the idea of designing programs as works of literature. In both cases your main focus is your audience, not the computer. The common principle in both is readability, but the idea of API usability takes it a little further because your audience isn’t just trying to understand what it’s looking at but actually use and extend the work.

I believe these principles of usability apply not just to API design, but to programs in general. Ken Arnold gives a couple of examples of UI principles applied to API design, such as the use of Progressive Disclosure. That’s the principle that says you shouldn’t overwhelm a user with more detail than they need for a common task, but rather disclose the additional detail when the need arises as they move further along in some interaction. Give the user what they need to know when they need it and only when they need it. That way they won’t be distracted or confused by superfluous information.

For an API, this might mean segregating the methods of a complicated class into the methods most commonly used by client applications from the less frequently used methods needed in special situations or by advanced users. For an application designer it might mean using interfaces and abstract classes to hide the distracting implementation details of a class.

Think about other common principles for user interface design, such those described in the Apple Human Interface Guidelines. How can these be applied to program design? I’ll list some more examples in the next installment of this column.

It may help to view your program less as a novel read in a single sitting and more like a TV show that is tuned in once a week by busy people with short attention spans. The purpose is still to engage and inform, but you need to keep in mind your audience could be jumping in to the story just about anywhere. Like a viewer flipping through channels, happening upon an interesting show, there’s a good chance that the first time a colleague comes across your code is clicking through the frames in a stack trace. They will be debugging an application trying to understand some unexpected sequence of events and will stumble upon one of your classes. Or they might drop in to use some small part of your API. Maybe they jump into your code to extend some capabilities, add a new feature, or make small changes as part of a global refactoring. They just want to know enough to get the task done and keep going. They might watch an episode but then move on.

There are a lot of practical implications to this approach but for this article I’ll just focus on one: give the user the information they need in the context of just “dropping in.” Think about the questions they might have looking at your code in a debugger: What is this class for? What elements are in the collection? Where did this member variable get set? Don’t make them work to find out something you could have made apparent with very little effort to begin with. Your goal is to give them enough information about each element so they won’t have to get sidetracked tracking down other references to the element just to see how it’s used . For example:

• Don’t make it a precondition for them to read a big design document on your intranet just to be able to understand what your GizmoClass is. Put the information as close to the artifact as possible. In the code, or at least in the same directory as the source.
• Document all your classes and interfaces. This may seem like a no-brainer, but it’s not about spending more time writing comments. Instead, keep it as simple as possible. Avoid verbosity and forms. Just a sentence or two to explain what the class is (especially helpful if you couldn’t come up with a really good name). Maybe say what it’s used for. That’s usually about as much as someone needs to know. Refrain from a huge exposition on the overall design or the justification for the class. Save discussion of the class members for the member comments themselves. And if you can’t think of something meaningful to say, don’t say anything at all.
• Don’t duplicate information in an Interface and a Class. If you have to pick one, document the interface. Focus on the interface for describing what something is or represents, and in the implementation, anything noteworthy about the implementation.
• When declaring variables of collection types, if you say nothing else in the comment you should at least state the actual type of the elements of the collection.
• Method javadocs are critical for the casual audience, but not because they will show up in the HTML documentation. Most IDEs will provide javadoc comments in a tooltip or property sheet, saving the user the step of clicking through to the declaration, or opening up the javadocs in a new window.
• Make variable names as descriptive as possible. Not just your member or local variables. People tuning in to your code the first time will have a much easier time decrypting your for loops if instead of i or index you use names like row, month, or customerNumber.
• Consider “Hungarian Notation” for variable names. Many developers find this convention ugly and onerous, but you can’t deny the value of immediately recognizing a variables scope without having to jump to its declaration. There’s a wide spectrum of adherence to this principle; from the old C++ practice of limiting the convention to member variables with a ‘_’ prefix on one hand, to an array of prefixes identifying the scope of every variable.

The point of this is not to enumerate a list of documentation standards for your programs, but to get you to think like an author and empathize with your audience. Use your own experience learning and debugging other people’s code to determine what your audience needs from your documentation. Give them whatever they need to keep them from changing the channel before your program finishes.

What is the purpose of a computer program?

Your colleagues and you all write software.  You generate software prose on a daily basis, crafting these artifacts called programs, line by line.  You utilize a common language that you all agree upon, a language which bears scant resemblance to a spoken language.  So what is it that you are creating?  What is the purpose of these lines of code?

You might say a program elaborates how a computer is to execute an algorithm.  It describes what the system should do and how to do it.  As programmers, we are the narrators and the computer is our audience.  That’s basically what we were taught in our very first computer class.

Donald Knuth, Professor of the Art of Computer Programming at Stanford University, challenged this idea over twenty years ago when he first proposed the idea of “literate programming.”  Knuth felt that computer programs were first and foremost works of literature, to be read and appreciated by humans more than computers.  A programmer should take the same sort of care and attention in writing a program that an essayist takes in writing prose.  He devised a special language called “WEB” which was basically a programming language that resulted in two artifacts: one compiled into the machine language of the computer and the other compiled into a document for humans.  A program listing in WEB not only read like an article, it actually looked like one because it was based partly on Tex, the typesetting language Knuth developed in the 70’s for publishing technical papers.

This would have been a much more challenging idea in the days before open source and tools that readily made source available and searchable, like Archie and the World Wide Web.  It wasn’t as easy to find examples of source code and even book authors were reluctant to disclose real applications in all the gory detail.  Most publications relied heavily on pseudo-code when trying to present samples for human consumption.  Before object oriented programming and the subsequent wave of class libraries and frameworks, programs had to do much more.  Real programs were just too ugly and verbose to put on display.

Open source has heralded in a new era of visibility for software artifacts.  The authors of Linux and Apache know that it’s not enough for their APIs to work as expected.  It’s not just how the systems behave that falls under scrutiny, but the actual source code itself.  The source of the Java Class Libraries makes itself known to most java programmers on a daily basis when they click on a stack frame in the debugger.  Successful open source contributors are very self conscious about how the source code looks.  The computer may not judge their triply nested loops but other programmers certainly will.  Their audience is first and foremost other software professionals.

So our program is a work of literature, then what is its purpose?  The purpose of our program is not to describe for the computer what we want it to do, but to describe for the programmer what the computer will do.  If that sounds subtle, then think about this the next time you are editing code in your IDE.  Is your “audience” really the computer?  Or is it the person in the office next to you?

Most conscientious programmers like to think of their code as maintainable–well documented and readable–but even the best of us may be tempted by obscure or clever shortcuts when we think nobody is looking.  Focus your work on a human audience.  If you’ve ever done pair programming, you know that having someone looking over your shoulder makes you take a bit more care with what you type in.  So imagine that someone is always looking over your shoulder, or that every line is going to be subjected to a team code review, scrutinized by your peers.  Write the code not for yourself, not for the computer, but for them.  Take pride in how your program communicates its cleverness, not just in being clever.  Choose names that not only mean something but could actually be read out loud in something that sounds like English.  Comments shouldn’t be an afterthought–your disconnected scribbled notes in the sidebar.  They should be interweaved in the source, flowing with it and filling in the prose to help the reader move effortlessly through the narration of what the computer is doing.  And remember: the best writers are avid readers.

Those are just a few examples of how programs should play to an audience of humans and not a computer.  I’ll be covering more in upcoming installments of this column.

But you’ll seldom hear him talk about himself. He is modest to a fault, which is one of his endearing qualities.

Bill Kayser

There are other interesting sides to Bill. In 1996, he took a six month sabbatical to sail as a deck hand on the tall ship HMS Rose, scrubbing decks and rigging up sails. He plays soccer fanatically and has badly scarred knees to show for it. Plus he’s often up to something fun – one day we played a prank on his sister, calling her with exaggerated Indian accents, telling her that we were calling from Dell Service Center in Bangalore, and that she should be careful while using her computer because it “might catch fire”.

Bill lives in Portland, Oregon with his British wife Crista, two-year old son Felix, and Boris the cat.

Anyway, Bill has agreed to write a series of articles exclusively for Nagarro that talk about the philosophy of programming and architecture. The first article of the series, titled “The Literacy of Programs” will be out tomorrow. Over time, we might put new articles up on a Wiki or a blog (internal or external?) and then you can discuss the articles directly with Bill. If you have any ideas of how we should structure this Wiki/blog, or you can volunteer to set it up, please do write to me. Plus if you want to write a note to Bill at any time, you can do so at bill@kayser.org.

We are excited by this initiative and look forward to seeing how this will work out.