Showing posts with label html. Show all posts
Showing posts with label html. Show all posts

Friday, March 16, 2007

Spotted: an HTML Button

"Good god, man... How a person can write so much about HTML buttons fascinates me." - A toli commentator

Per Google, I have an unseemly amount of clout when it comes to the subject of the HTML button born of 9,000 word folktales bemoaning its general under-appreciation and lack of use.

I've always felt guilty that I didn't offer more prescription to the 50-60 searchers who daily come across that piece. Still I thought I was only stating the obvious (albeit at length, and with tongue in cheek).

Thus I was pleased to note yesterday that Google Reader switched from its misguided use of simple hyperlinked text for its "Refresh" and "Mark all as read" functions to now use items that look like html buttons. I won't bemoan their developers not using native html buttons since they've at least recognized that it is best to have clear indicators for potentially unsafe operations. I wonder when Bloglines will follow suit...

google reader uses buttons

I'll echo Phil Ringnalda again:

Making the fire alarm look just like a light switch isn't an example of daring and innovative design, it's just dangerous.
These small usability tweaks add up to broaden the appeal of the web which after all is our great mass participation medium. My rule of thumb in systems design is that we should favour participation over control. I believe this notion extends to user interface design. Giving up full control of the user interface in favour of standards tends to benefit an application because it often meshes with user expectations. There is paradoxical joy to be found in a constrained design space.

A parting sidenote: for the past few months I've been working on the Dojo toolkit, that open source javascript toolkit. At a certain point it was vaguely suggested that I work on form widgets including developing custom buttons. As you might suspect, I immediately demurred and disqualified myself pointing to my paean to html buttons. My position is unchanged: in as much as possible, one should use the built-in browser components and lobby the browser vendors to implement XForms, Web Forms 2.0 or whatever standard can improve the experience of building form applications on the web. HTML forms have been second class citizens for too long yet they are essentially the equivalent of Mary Magdalene and the disciples - the foot soldiers of the web style (digression: Bill de hÓra has been grumbling of late that HTML forms are the original sin of the web). I am pleased to see movement on many fronts these days. Every little bit helps I suppose. Let's celebrate these small things:


Next: The ballad of the link

File under: , , , , , , , , , , , ,

Sunday, March 19, 2006

The REST Elevator Pitch

The Pitch


I somewhat share Ryan Tomayko's concern for a shorter hand language for describing REST (Representational State Transfer), but I believe that the REST elevator pitch is pretty succinct already. It packs a lot of insight into the web architectural style of which dissertations have been written. The language used in technical debates is always important and rather than devolving into the fuzziness of "highs and lows", I'll suggest here that, as a matter of advocacy, one should stick to the elevator pitch.

To recap, the REST elevator pitch is:
  • Identification Of Resources
  • Manipulation Of Resources Through Representations
  • Self-Descriptive Messages
  • Hypermedia As The Engine Of Application State
In its most common application, the pitch will lead you to the HUHXtable Quartet (HTTP / URI / HTML / XML) if we handwave away the additional content types that the web style enables you to negotiate. It is quite clear that applications of all kinds have been built on these fundamentals for both human and machine interaction.

The thing is that each plank of the pitch brings its own benefits, benefits that perhaps can accrue independently. Still you get the most bang for the buck at the internet scale by the principled combination of all of them.

In my advocacy I tend to start with resource identification as the most important plank. The reason for this is that everybody can understand the value of identification. My grandmother understands the value of a bookmark to my photos. Heck we are even seeing the social benefits of ostensibly selfish bookmarking. The importance of resource identification cannot be understated and it leads us to the primacy of the URI.

The second plank, manipulation of resources through representations, is the bread and butter of HTTP, where we have an evolving set of standard formats of hypermedia exchanged using a small set of verbs.

Unpacking the HTTP proposition leads us to the four horsemen of the web: GET / POST / PUT / DELETE

Of course you can do very well if you pick up only 2 of those verbs, GET and POST. The good Reverend HTTP is a pretty tolerant fellow and won't begrudge those that don't believe in the rule of four, although in admittedly imperfect analogies, there's CRUD (Create / Retrieve / Update / Delete) in the database world and, as far as this layered internet goes there's TCP / IP / Datalink / Physical Layer (with say Ethernet or "Wi-Fi" 802.11b/a/g)

On the other hand, if you want to be a good citizen in the town of Deadwood and indeed if you want to survive in the wild west of the web, you shouldn't abuse HTTP. HTTP abuse leads to user confusion, headaches for systems designers and a tragedy of the commons. I consider HTTP a deliberately minimalist compromise, laissez-faire distributed computing if you will.

In social settings making your intentions known can help smooth interactions. We may start with small talk but we eventually manage to discern where others stand - well most of the time at least. We all operate with imperfect information but being straightforward is often a great policy. I'm sure there's some game theory or behavioural economics that can point to the value of transparency. Perhaps it is trite in light of Machiavelli and Sun-Tzu to believe that disclosure is the best policy but at least in markets transparency tends to be the font of aggregated wisdom. On the internet scale, this translates into the notion of giving visibility to intermediaries. Arguing again by analogy, the internet is an agreement, a network of networks. You can do whatever you want on your network but to interoperate with others, a small set of primitives, the TCP/IP standards in this case, have been agreed upon. I would suggest that the web style is similarly such an overlay system. REST is an architectural style which by principled design, is optimized to lower coordination costs.

Acknowledging the benefits of idempotency, of doing things safely, will lead one to making sure the use of GET is safe. Idempotency is not just about safety however; in clearly signaling your intentions, it is also about replayability. Thus idempotency is not just about the GET method. That is the wider argument for also using that oft-neglected duo, PUT and DELETE. Tunneling everything through POST (and the completely aberrant case GET) may be convenient but it adds unnecessary opacity and unpredictability about one's application. Unpredictability in the world leads to invasions and worse I might add. The use of those four core HTTP verbs helps intermediaries understand and participate more fully in the ecosystem.

The last two planks of the REST elevator pitch, self-descriptive messages, and especially that last one, hypermedia as the engine of application state, are attempts at addressing the issues of state, caching and evolving systems amongst other things.

Now of course in the preceding paragraphs, I've handwaved away entire dissertations that have been written about architectural styles and systems design, tomes written with language more precise and concepts more subtle than I've outlined. Good samples and running code are often also a determining factor in which style or application is adopted thus the view source imperative is also one of the reasons that web has caught on so quickly.

The Hard Problems


I've recently been thinking about defining the hardest problems I've encountered in software engineering, my cursory top 10 list:
  • State
  • Caching
  • Latency
  • Concurrency
  • Search
  • Metadata
  • Persistence
  • The Holy Grail Of Extensibility
  • Structured data
  • Character encoding
Now I'm not a database person so I handwaved away all of those data peoples' worries in one word: persistence. Of course I should probably add a few more issues and indeed you probably have your own notions. Indeed I settled just two days ago on those last two, structured data and character encoding, when I characterized them as being the gruesome twosome of computer science. Perhaps also there's the issue of discovery and bootstrapping of a system but that could be considered implementation details. There are those who mention security and reliability as other hard problems and they certainly are. Still I'll also handwave those away not as technological issues but as transaction costs; the economic benefits of ubiquity and leverage are key here. It seems that humans are quite prepared to tolerate gremlins and parasites in their systems (social, biological and technological) in moderation of course.

What is interesting is that almost all of these issues are important even if you aren't dealing with distributed computing. On the internet, which is all about distributed computing however, these are crucial problems. Now addressing these problems is a pretty tall order I must admit, but it seems to me that the web style has concrete answers to almost all of these constraints. Furthermore REST also offers a couple of those very valuable system characteristics: resilience and adaptability, almost as externalities.

Search for example seems to be addressed by valuing the importance of resource identification, the URI, that leads to PageRank and other algorithms. If you start with a viewpoint that URIs are cheap, and if you model your resources appropriately, you can deal with concurrency quite reasonably. State, caching and latency are all to do with performance which is always a bear. To that I'd argue that the commerce that is taking place daily on the internet seems to be a good indication that things are acceptable even if they could be improved. Metadata is the eternal headache of course but HTTP will give you headers and soul to help a little.

Discovery is addressed by URI as identification, the notion of hypermedia (either link headers or references in the media) and perhaps the current best practices of introspection resources. Persistence and structured data, I'll argue, are being addressed, warts and all, by the relational database, the seemingly-unstoppable spread of XML and, I believe, the current ascendancy of feeds. On this last subject, the wiring of the web, I am cautiously optimistic that the Atom store dream could be an answer; i.e. the combination of feed format (say Atom/RSS) and a wire protocol - which perhaps the Atom Publishing Protocol or similar could be. On the question of extensibility, last year I started a response that I felt was needed due to Dion Hincliffe's unbelievable assertion that "extensibility was the Achilles heel of REST". It always takes me a year to respond to minor footnotes but if there's one thing I'll do in the next few months, I'll be sure to write about REST and the Holy Grail of Extensibility.

But anyway, that is getting ahead of myself. I've been told to save my musings for "the book" or to stick to writing the running code that will "show, rather than tell" yet I keep falling for this web as conversational engine. Still there are undoubted social benefits of these exchanges and perhaps conversations like these are another virtue and externality of the web style. In any case, consider this my long winded response, Ryan: in matters of technology adoption and systems design, let's stick to the elevator pitch.

Further reading:

The Sequel


[Update - March 27, 2006] It seems as if everyone is getting into shaping the pitch and the language has been quite interesting.
  • Danny Ayers remarked that we should go back to the source and points at Tim Berners-Lee's pitch from last year
    Web architecture 101
    • Things are denoted by URIs.
    • Use them to denote things.
    • Serve useful information at them.
    • Dereference them.
    That indeed is about as brief a pitch as some executives will be able to handle and it covers the essentials.
  • Tim Bray's pitch is fairly pithy too, and for the last plank he uses
    You expect to ship a lot of URIs around in the bodies of requests and responses, and use them in operations that feel like link following.
    Now that's quite a mouthful in a presentation but it works fine in an elevator. I think "dereference them" is more terse and captures much of the same insight.

    As an engineer who is interested in precision in language, I tend to prefer Roy Fielding's formulation of "hypermedia as engine of application state". It's short and alludes to both the implementation and the area of focus of the web style. But your mileage may vary and I think it depends on the audience. We should be interested in a pitch that works because the advocacy struggle isn't over even if some are already thinking about the future issues. In this light, it was good to see Joe Gregorio again emphasizing the Show me the code route he embarked on last year. That View Source Imperative is the secret ingredient as far as adoption goes.
Note that everyone seems to conform to the Rule of Four as far as bullet points in the pitch go. Interestingly enough, Roy Fielding used to go with a five point pitch until he merged what were his previously separate definitions of "resource" and "URI" into the phrase "Identification Of Resources". I've proposed my own four point plan as a model for ArRESTed Development or The Low End Theory.

I concur of course with the endorsement of the formulation of REST - the web style and not just because I seem to have juice (of the google flavour) on that front having internalized that phrase long ago in my interventions, but because it gives us a tag, REST, combined with a catchphrase. As we know, every movie needs a tag line. Especially in Deadwood: "6 million ways to die, choose one". That is the B-movie of distributed computing. We want to move beyond grindhouse pulp fiction and get some of those glamourous, golden Hollywood trophies. And if that fails there's always the Gospel of REST.

The Elevator Soundtrack

  • Outkast - Elevators (Me & You)
    The chorus of this laidback piece of Atlanta folklore could well be a stand-in for the inclusiveness of the web style and its architecture of participation.
    Me and You
    Your Momma and Your Cousin Too
    Rollin' Down The Strip On Vogues
    Comin' Up Slammin' Cadillac Doors
  • [Update] A hat tip to the good doctor, Ernie Prabhakar, who points to a real life Huxtable Quartet. When I first started using HUHXtable, I was thinking of the Cosby Show and of comfy sweaters, thus it's great to hear that the Slide Huxtable Quartet is itself a tribute to that show and to the "Play It Again, Russell" episode in which Cliff's father, trombonist Russell "Slide" Huxtable (Earl Hyman) hosts a jam session. REST has even got a house band.
  • Miles Davis - Ascenseur Pour L'Echafaud
    I've always loved Miles Davis's cool soundtrack to one of the great film noirs which saw a great print released last year. It's atmospheric and gets the job done - and with verve. I am always upset that ascenseur is translated as lift rather than elevator which is more heady to my ears. I'll conclude by suggesting that the web style will save you from heading up the Elevator to the Gallows.


File under: , , , , , , , , , , , , , , , , , , ,

Friday, March 17, 2006

Minutiae

A surprisingly large part of a software engineer's life is spent dealing with the little things. Much as I like to write about grand designs and architectural issues or people, processes and communities, all too often, the devil is in the details and I get lost chasing technological quirks. Herewith a sample of just the past week's minutiae, perhaps fodder for historians of science or anthropologists.

Boolean Identity Crisis


I was going over some code in my pet XForms processor implementation and wondering what was going wrong - incidentally IBM has written (at least) 6 forms processors in the past 4 years along with contributing to the Mozilla XForms effort but we won't get into that - I'll save that for a business school case study or something.

After an hour or so of head-scratching this was what I found. In XML Schema Datatypes, the lexical space of boolean values includes not only "true" and "false" but also "0" and "1". I assume the inclusion of 0 and 1 in the specification comes from the legacy of the C language and presumably that makes sense. But I ask, was that a wise decision? The designers of the specification chose a binary representation in a textual format.

The forms processor is written in Java. It turns out that in the Java language, the lexical space of boolean values is case-insensitive "true" and "false". So if you have a mapping layer that goes from schema datatype to Java you have to add special case code to deal with 0 and 1. Presumably also in the other direction, you have to make sure that you don't output "True" instead of "true". I had been linking to a library that hadn't bothered to implement this more robust logic and ran into this boundary condition. Oh well, I thought, I'll have to add an adapter around this library or rip it out and roll my own - an assignment for the weekend.

I vaguely remember Sam Ruby mentionning that this was one cause of interoperability issues between SOAP implementations and it stands to reason: we've codified an identity crisis.

Structured Data Footnotes


Jon Udell is a careful man whose
blog works differently from the rest of the InfoWorld blogs. The content is well-formed XML, and it follows certain self-imposed rules.
This discipline enables him to work miracles and regularly come up with lots of cool applications. But in the wider world, getting people to author structured data is an often intractable problem. XML is often structurally invalid; as an example the Google Reader team have reported that 15% of feeds on the web are not well formed and that is before considering the feeds' semantic validity.

Thus I was tickled by this footnote he wrote when playing with microformats.
The difference? I ran the page through HTML Tidy to get well-formed XML 2...

2   It wasn't entirely automatic, unfortunately, I had to wrestle with character encoding issues too.
Ladies and Gentlemen, I give you The Gruesome Twosome of Computer Science: Structured Data and Character Encoding. We call them footnotes.

Highlights, Lowlights


It started with an offhand comment, a report that one couldn't set the background color on text in the rich text editor in Mozilla Firefox. Every other command on the editing palette worked. You thought, "15 minutes tops, I'll take it".

So you look up the list of command identifiers in Internet Explorer and notice that the execCommand method has an attribute named BackColor which
Sets or retrieves the background color of the current selection.
You head back to the Midas spec for Mozilla and see that for the backcolor entry
This command will set the background color of the document.
Hmm... Your first thought had been that it was a case-sensitivity problem, "backcolor" rather than "BackColor", but the documentation notes that case doesn't matter. So the problem is rather what you highlighted, in Mozilla, backcolor applies to the document and not to the current selection. This means that you have to use a different identifier to achieve the same effect in Mozilla. You promptly notice one called hilitecolor
This command will set the hilite color of the selection or at the insertion point. It only works with useCSS enabled.
Okay, someone decided to not use the same command as Internet Explorer, fair enough, you've seen worse. As you change the code, you say, it's Mozilla and CSS is enabled by default so all I have to do is switch to using hilitecolor.

Of course that doesn't work. You then tell yourself that you'll just enable CSS with the useCSS attribute (you had looked more closely at the code and noticed that CSS styling had been deliberately turned off for some obscure reason).

Hmm, that didn't work...

So you go back to the spec and you notice a styleWithCSS attribute. Interesting... You try that instead of useCSS. Of course, you happen to be testing using a version of Firefox (1.04) that doesn't support that attribute so there's an exception. Presumably this attribute was introduced in Firefox 1.5 or something. Still it's a good thing that you are using an older version for testing otherwise this would have been another bug (feature doesn't work in Firefox 1.0 etc).

You bang around for a while and go back to the original Midas demo which seems to work correctly if you have the "use CSS" checkbox checked.

You view the source of the demo to figure out what could possibly be making it work and you notice that they are setting the useCSS property to false when the checkbox is checked. Huh? They set useCSS to false in order to enable CSS!

So you go back and look more closely at the documentation. First you notice that the useCSS property is deprecated. Hmm... the plot thickens. Then you read this
useCSS - value: true/false

Note: This command has been replaced with styleWithCSS. It takes the same values as styleWithCSS, but the meaning of true and false are inversed.
Up is down in other words. It's like Alice in Wonderland or something. Do note that there is no word on what version the replacement occurred. Nor indeed is there any footnote on why true and false are "inversed".

Anyway you've finally figured it out, you make the change to enable CSS styling only when applying the hilitecolor attribute, add some future-proofing to use the styleWithCSS attribute in case the deprecated useCSS attribute is removed in later browsers, submit the patches and 3 hours of your life have passed. It was frustrating but there's an object lesson somewhere. If you are building a robust cross-browser rich text editing application, you have some code that has to go through this rigmarole.

I have a confession. I recounted the above tale because I feel guilty: I could have prevented all this four years ago.

Internet Explorer was the first browser to introduce rich text editing. It was not pretty since they didn't want it to be as good as Microsoft Word, but it worked reasonably. IBM later contributed resources to Mozilla to beef up its rich text editing. Indeed four years ago, I was asked to review the resulting Midas spec by my colleagues who had been working on that functionality. The spec looked serviceable, pointing mostly to the Microsoft documentation since they wisely chose to follow the de-facto standard. I reported a few bugs with the intial implementation and we built a rich text editor around it. It's widely used on the web these days.

I obviously was a bad reviewer because I certainly didn't notice that there was a change in the semantics of the backcolor attribute from "current selection" to "document" nor indeed that a new attribute, hilitecolor, had been introduced in Mozilla. There is absolutely no reason for these discrepancies. Nor do I want to go down the forensic trail that explains why you can't have a background color on text if you don't style with CSS. That's a rathole of its own.

So what do we have here? A de-facto standard was implemented but someone took the liberty to change one aspect of it for whatever reason - semantic purity or something. I suspect I won't be the last developer to waste an afternoon on this or indeed the last user to be cursing about why I can't add a background colour to a piece of text. I hope that Opera and Safari, if and when they have their rich text editing implementation in place, will do a wholesale copying of Internet Explorer's behaviour. I don't want to be chasing these lowlights again. I often see criticism of Microsoft's inconsistent approach to standards but everyone can be as guilty as them on occasion.

Which Side Are You On?


Stefan Tilkov recently asked what's wrong with Javascript? The answer of course is nothing really, it's a fine language as evidenced by looking around current thinking on the language. Indeed Brendan Eich's biggest admitted gotcha about the language is automatic semi-colon insertion. Thus there is no reason it can't be used in environments outside the browers in which it is most widely deployed as glue - I've played with Rhino on the server-side without any problem.

From what I understand, Jotspot, which incidentally I consider a cunning plan to showcase the Dojo toolkit, uses Javascript as the scripting language on both the server and client. All power to them. Of course with Javascript from the same document executing in both environments, you can get very confused. The answer to one of Jotspot's most frequently asked questions, "Why isn't my Javascript function being called?" is that "your code is not running where you think it is" ergo, you're expecting that the current code you're looking at is server-side rather than client-side, or vice-versa. This is especially true since the object model is likely to be different, the browser DOM is a deliberately constrained environment whereas on the server side you'd want to allow your plugins to do more.

Thus there is a little impedance with using Javascript everywhere. Perhaps it's less confusing to use a different language and syntax for server side code - a tag library in jsp, or embedded java, php, asp or whatever. Or maybe clever syntax coloring in your editor or IDE would do the trick to remind you of the context. Needless to say, you have to decide what side you're on...

I've been working on a project in which the others on my team are seasoned PHP gurus and are occasionally petrified of Javascript - the reason of course being the continued brittleness of the browser platform. When I started work, this bias showed and their initial recommendation was to do as much as possible in PHP on the server-side. They recognize however that that we are living in an age of interactivity so we need that shine that comes with moving intelligence to the client. Still when you start doing data-binding and automatic JSON serialization of PHP objects, you get constructs on the browser client that you wouldn't normally use if you were a client-side person. As someone who's very comfortable with both client and server side code (perhaps more comfortable with Java than PHP), I keep running into such peculiarities all the time. Of late I find myself prototyping code in client side Javascript even if it will eventually morph into server side code. Perhaps I need to get more into Python or that Ruby bandwagon. Still you tend to develop a split personality when you develop for the web.

The Null Hypothesis


I got the note: "you can't append a column if you click on a cell in the last column of a table in Internet Explorer".

Huh? I attempted to reproduce the bug and, sure enough, that was the case. Vaguely at the back of my mind I recalled from painful experience in K-station that there were special APIs in the HTML DOM for dealing with tables. Thus I searched the codebase for insertRow and insertCell. Hmmm those functions were nowhere to be found. How were they doing the column insertion, I wondered? My guess was that this was either some innerHTML tricks or simple standard DOM manipulation. Thus I had to dig through the code and eventually encountered the Node.insertBefore conundrum.

Now insertBefore is a method on the Node interface that is part of DOM level 1 specification. Every browser claims at least DOM level 1 support.

It turns out that in certain versions of Internet Explorer the second parameter to the insertBefore call can't be null, you get an Invalid Argument exception. Mozilla handles this condition as one would expect in their Javascript binding; Internet Explorer chokes. [Obscenity]. There was too much code to change to use the HTML-specific methods so I just hacked special case code that ensures that I don't pass a null to Internet Explorer - 3 hours of my life perhaps.

Now this doesn't amaze me really, thinking back on it, this is probably the reason that somewhere in the bowels of every Javascript library that deals with dynamically adding a new option to a select control, you'll find code like the following:
function appendOptionElement(select, newoption){ if(is_ie) // test for internet explorer somehow   select.add(newoption); else   select.add(newoption, null); }
The browser is a fragile place and hopefully the frameworks that are being developed will shield you somewhat from such issues, but it is telling that you can't rely on core DOM functionality. Even if these quirks are fixed in Internet Explorer 7, this patched-up code will have to hang around for another 5 years before users will no longer use older versions of the browser. We're in a world of pain in the browser world.

Nulls however are problematic throughout computer science. The arguments around them may sound like angel and pinhead discussions but they are fair questions. What indeed is null? What is zero for that matter? For centuries and throughout the Dark Ages of the West, there was no concept of zero, it took Arabic Algebra to spread that notion. Why should one expect that programmers would have internalized the null concept? Reasonable people can and do differ on how to treat null.

Just now, reading through the latest Dr Dobbs journal, I noticed the following in an article about Consuming .NET Web Services in Oracle JDeveloper
The ATL Server SOAP handler generates an xsi:nil="1" attribute when the element's value is null, or when the array is null or zero-size. Unfortunately, Apache SOAP fails to deserialize UDTs whose fields contain the xsi:nil="1" attribute and expects zero-size arrays to be represented as XSD arrays with the dimension parameter set to zero.
The author then proceeds to outline a variety of workarounds. Now I happen to not be a fan of the SOAP style of programming (in the past I've called it Crusty Old Architecture pronounced SOA with a silent P) but as a developer, I feel the pain. The article is a catalog of kludges and likely mapping errors that have to be worked around - the word "unfortunately" is used entirely too often.

I started my career doing graphical programming thus I perked up when Raymond Chen recently outlined the consequences of invalidating the null window and his anecdote is worth quoting at length.
If however you end up passing NULL as the window handle to the InvalidateRect function, this is treated as a special case for compatibility with early versions of Windows: It invalidates all the windows on the desktop and repaints them.

Even more strangely, passing NULL as the first parameter to ValidateRect has the same behavior of invalidating all the windows. (Yes, it's the "Validate" function, yet it invalidates.) This wacko behavior exists for the same compatibility reason. Yet another example of how programs rely on bugs or undocumented behavior, in this case, the peculiar way a NULL parameter was treated by very early versions of Windows due to lax parameter validation. Changing nearly anything in the window manager raises a strong probability that there will be many programs that were relying on the old behavior, perhaps entirely by accident, and breaking those programs means an angry phone call from a major corporation because their factory control software stopped working.
The null hypothesis strikes again.

Camel Humps


Even when you get past these details, you get into matters of syntax - a longstanding pet topic of mine. Consider the separators that people use for readability. Some people like to use Hungarian notation, others prefer hyphens... well I've already written a hyphenated parable so I'll skip that aspect. Anyway, assume for some insane reason that it makes sense for your spec to have an attribute named "windowTop". There'll undoubtedly be people who will write it "window-top", "window.top" or with some other variant of case, "WindowTop"? If you're dealing with XML where case matters, things will fail. You say potato, I say pubDate anyone?

I've been playing with a product that is essentially a wiki and it turns out that by convention, camel case (or should I write it as CamelCase) is significant in the wiki world as denoting a "WikiWord". I even had to spend half an hour writing glossary entries for these concepts since in our system, user names and page names had to be in that format.

You can imagine however the kinds of issues that arise when you have an html editor that allows you to enter HTML and Javascript along with php code and a specialized wiki syntax - since for some reason, it was decided not to use angle brackets in this product. The most complicated piece of code is going to be the parser. As currently implemented, the parser is a mass (or should I say, a morass) of regular expressions and all kinds of things I'll never understand. There's even special case code in there to handle nested comments in Javascript. What was never forseen however was that you'd have to deal with user-entered script code. What would happen if camel case is used for variables inside of said script? Well it wasn't pretty when the wiki engine jumped in and treated script as wiki words, let's just say that someone had to come up with a solution.

There's this concept known as McCabe Cyclomatic Complexity which is basically an application of graph theory to software and is often used to pinpoint potential problems. The basic insight is that if there are too many decisions or paths through your code, it will be buggier, harder to maintain and test. A good guideline is that anything with complexity greater than 15 in this scheme is ripe for refactoring. Luckily I have access to some tools that can generate reports and provide some numbers to validate that nagging sense that a piece of code is getting harder to understand. What worries me is that I keep running into code that laughs at such guidelines - after the latest change the parser code just hit 41 (to give some context, values between 21 and 50 indicate "a complex, high risk program" and with the 50 barrier looming, we are verging towards that notable status of the "untestable program - very high risk"). I'm sure it didn't start out this way and that the steady accretions have been solutions to real problems. Still, technical arteriosclerosis continues its inexorable spread...

Ruby on Rails and the Zend framework for PHP are founded on favouring convention. We had this code that automatically created the schema for what amounted to a database table. We never actually told users that this was what was going on. Of course once a wider audience started to play with the product, we had to fix the bugs that arose to enforce the convention so that databases would be named as the code expected. A classic case of leaky abstractions I suppose. You can guess the complexity the additional error checking added.

Moving up a level, you get politics - the most aberrant of which have been the feed wars of the past few years perhaps best summarized hilariously by Shelley Powers. Truly, Jesus wept.

Bill de Hóra in an aside wisely noted that
Programmers would rather squabble about minutiae - it seems this transcends community or language choice.
But even when you move beyond whiplash and abrasive personalities, who would have thought that the Atom working group would have spent so much time on the concept of dates. When I saw dissertation-length essays on the various types of dates that might be used in publishing systems, I was content to continue lurking in that community. The thing however is that these details do matter and they are best dealt with up front. The aggregate waste of programmer effort in pursuit of minutiae might keep the profession in business but it surely isn't sustainable.

The East Australian Singularity


I'll conclude by noting that acts of God (or in this case, his flawed proxies: politicians) can come into the picture. Thus I read the following this week: Eastern Australia: Java applications impacted by the change to daylight savings time dates
The running of the Commonwealth Games in Australia in March and April 2006 has resulted in an extension to daylight savings time in the eastern states of Australia, which includes New South Wales, Victoria, South Australia, Australian Capital Territory and Tasmania.

Rather than the clocks being put back an hour at 03:00 on Sunday 26 March 2006, they will now be adjusted at 03:00 on Sunday 2 April 2006. The IBM Software Development Kit (SDK) or Java Runtime Environment (JRE) is not currently aware of the one-time change to the daylight savings time extension. An interim fix is required for your application to have the same time as your operating system.

This change applies to all of the Java environments, irrespective of their setup, whether they are set up to use the operating system time zone information, or the user.timezone custom property that can be set for the SDK or JRE.
I assume television schedules were behind this change to the time/space continuum since the Commonwealth games have just begun. Or perhaps the politicians were concerned about athletes missing their events or something. Still imagine if you're the Java programmer who has suffered through the badly defined date apis in Java 1.0 a decade ago, adapted to the improvements in succeeding versions and finally, finally gotten a robust application deployed. Then your manager walks in and tells you about the East Australian Singularity. You're going to have to rework everything since bank transactions might be messed up and there are likely to be blinking clocks etc. We live in a global village so you have to worry about what happens if some mission-critical application that you rely on is being run in Eastern Australia. You can't even have the special case restricted to that country, it's only a sub-region that is affected. At such times I'd prefer being the poor Eastern Australian sheep or lamb, their lot is much easier.

What a way to make a living, if it isn't one thing it's the other. And then there's version hell. Lord help me.

File under: , , , , , , , , , ,

Wednesday, May 11, 2005

The Unloved HTML Button and Other Folktales

A long, long time ago in a far, far-away land, there lived an HTML Button.

It lived happily with its parents, Mr HTML and Mrs Form, and its siblings: the older brother Text Entry Box and younger sisters, Drop-down List and Radio Button. As a family, they didn't look like much, but they got on with things. Indeed some would say that they had been second thoughts since grand-parents, Netscape, Microsoft, Apache and Berners-Lee, preferred to fawn and monopolistically squabble over cousins, Blink and Marquee Tag, the mobile duo, Java Applet and ActiveX, and the gruesome but quietly efficient twins, CSS and JavaScript. Let's not forget the ugly outlier, the Behaviour, and that perennial favourite of old Sir Tim, Semantic Purity. Still those pragmatic matchmakers, Fielding and Andreesson got together, sacrificed a few goats on the altar of sloppy expediency and dotcom hubris respectively and got the marriage together. The good Reverend HTTP was the officiating priest. Thus they called for a great many festivities and plenty palm wine and Schnapps was consumed by the merry populace. Yahoo! and Google, they ululated as they devoured the fatted Browser calf.

The Lord looked unto them and saw that it was good. He was pleased with his creation, thus he thundered: "Let my children prosper. Go forth and multiply forthwith". The VC Angel of the Lord blessed them with a strong essence and wide child-bearing hips. Verily I say unto thee, many offspring were spawned throughout the land. This allowed Uncle Amazon and Auntie eBay to garner many an oxen, selling little e-commerce gnomes on the child labour, and great work-ethic, of these precocious, and outsourced, children. The UPS town criers beat FedEx talking drums loudly and strew countless packages in villages from Kokomlemle in the south to Bolgatanga in the north, all the way to the far corners of this Flat Earth we live on. Big Blue-suited Armonkians day-dreamt of middleware and on-demand eBusiness, Oracles everywhere hummed expensive ballads of Databases, and itch-scratching Scandinavian Viking ants from the village of Linux (they were of the GNU genus) began to colonize many a continent.

Seeing all the fun they were having, Godfather Bray and Grand Wizard Paoli spawned another cousin to add to this fertile mix: the virtuous XML. Of course you have to understand that back in the old days, before all this boom-boom stuff, Real Men could hug each other without fear of overzealous prosecution.

XML was a boy genius. As an industrious type, he was singularly prolific and many offspring were issued from his legendary nightly encounters including the incomprehensible RDF and the Siamese twins XSL and XSLT (but we all have skeletons in our closets), and those sloppy but similarly prodigious critters, RSS and Atom, who founded a land called Blogosphere and struck fear into all and sundry so unruly was their behaviour. The Ananse's web that was woven was wondrous and resplendent in its glory. Hosannas were sung and there was much myrrh and frankincense which caused much mirth and frankly increased the joy felt by all who alliteratively assembled at the proceedings.

Periodically however, people got jealous and countless trials and tribulations were launched in the direction of this happy family. Where others would turn to ashes and sackcloths, throughout they kept the faith, and never complained about the insane contortions that those two wicked aunts, Gertrude UI Designer, and the quadruple-barreled Felicia Unsatisfied-Application-Framework-Developer, made them go through. Still, with the help of those Glue Layer People, Shadrach, Meshach and Abegnego who came armed with duct tape and spanners, they persevered in the righteous way. They were kindly sorts, steadfast, humble and true to the Lord. As I start my tale, the future looked ever so bright for them.

Lest you think I have too much time on my hands or that I don't have a day job, I should preface my folktale by saying that it was actually 10 months ago in Cambridge that I started writing a few fragments for what I codenamed the Toli Technology Series. And so, dear reader, the topic of this long-mulled note is that fair and foulweather friend of ours: the unloved html button and its form family.

Now 9 or more months from conception to birth is typical for me and for most mammals even if it is a long time in the technology world, and it leaves much opportunity for others to make much the same point and vividly so. Thus I can make no claims to originality or insight. I happen however to believe in Gabriel Garcia Marquez's maxim that

"Any idea that couldn't stand a few decades of neglect is not worth anything".
My first novel is certainly pushing in that direction but that is water under the proverbial bridge.

Before I get into our tangled tale of prodigal buttons, let me begin by recounting what prompted this current jaundiced delivery...


A case of mis-directed advocacy


Over the weekend, in one of my episodic eruptions, I found myself trying to knock heads together to make sure that the right lessons had been learned in the reaction to last week's release of the beta of Google's Web Accelerator (GWA).

To give some context, the GWA is simply a client-side proxy server application that can speed things up for the user by making use of Google's wonderful infrastructure. Of course Google have other reasons (read metrics) for introducing this product but there is some real innovation here (additional compression of documents, the insightful idea that only updates to documents are transferred, the so-called differential exchange, and, most of all, leverage of the scalability of Google's unparalleled and massively parallel server farm). The browsing experience for millions of people could be markedly improved especially for those on dialup if this product is widely adopted. This is plainly an opportunity for the immediacy of communication, conversation and plain social intercourse to further flourish. I won't even dwell on the likelihood of this product further lubricating promiscuous commerce throughout the land.

Thus it would seem a caching intermediary like Google's should be fair game. Caches are used everywhere in the internet and there were a lot of tradeoffs that were made in the architecture to accommodate them. HTTP bends over backwards to make possible the magic of such intermediaries. Indeed almost all the differences between the HTTP 1.0 and HTTP 1.1 specifications relate to this issue of giving visibility to intermediaries. Tim Berners-Lee's prototype was turned into the "product" we know by repeated contact with the real world.

The trouble however is that many people, almost since the beginning of our tale, have been abusing HTTP and misusing its semantics especially as regards HTML forms and their offspring. People regularly use hyperlinks, the kind that you would type in in a browser location bar, to cause side effects. This goes against the injunction in the good book that goes under the name of idempotency.

Google's web accelerator in barely a few hours exposed how widespread this abuse has been. Like an assiduous cache who had read those ancient tablets, GWA simply assumed that there would be no side effects to performing an HTTP GET on a hyperlink on a web page, it did so and tried to prefetch things intelligently. Of course since these hyperlinks were doing unsafe things, sometimes things got deleted. Now this train wreck was predicted in the wise counsel of the Reverend HTTP in his opening address and the toast that matchmaker Fielding gave at the wedding where the whole world was invited to witness. Apparently however, many of the guests were drinking too much; their calabashes runneth over with Schnapps. The Yahoo! and Google choruses were rather symptoms of their inebriated bubbly state.

That being said, I was actually surprised that some of the brightest and most inventive developers around were metaphorically caught with their pants down, dead drunk, and, even worse, that they were then protesting their good intentions and rectitude. I was therefore fulminant when I weighed in:
There is an architecture to the World Wide Web.

Truly.

Really.

I kid you not, there is an architecture to this messy thing that we live on. This architecture was worked out in blood, sweat and tears (and a lot of fun during the dot com boom) over the past 15 years in countless mailing lists, with countless dear lessons learned.

Now when you start a post in that vein, what is to follow might get a little heated. As ever, I should have been calmer and like Joe Gregorio framed that episode as a parenting lesson:

I'm sorry, I can't kiss it and make it better.
I firmly believe there are just some things that a child will only learn through experience (read pain). Many times children can just be stubborn, or choose not to believe you, and ignore your warnings. I understand this. I did this myself. No matter how many times my parents told me that the iron was hot, it wasn't until I actually touched it and burned my finger did I believe them. That feeds into my parenting strategy, if they misbehave and end up in pain, I believe that's the right time to reinforce the message, make sure the lesson is tightly coupled with the pain, that way they're less likely to forget.
Instead my discourse devolved into a case of I told you so, a kind of Old Testament view of things instead of the softer New Age stylings that are in vogue these days. Sure there was a little concern for the users that had been hurt by lost data, but there was almost no empathy for the developers who had to lose their weekends furiously reworking their applications to do the right thing especially because it appeared that they would rather persist in trying to do the wrong thing.

The sentiment behind that mini tempest-in-a-teapot however was a recognition of the fact that those who have been quietly evangelizing the web style were talking about the wrong thing and to the wrong people.

Advocacy is great on xml-dev and the various forums where the REST/SOAP debate is played out but it is missing entirely the audience that counts. We might as well ignore those RPC and "complicated framework people" even if their claims are sometimes so unbelievable. Thus I believed that my own REST intervention and the countless other inquisitions were a touch mis-directed. According to de.lici.ous, 30 people appreciated my piece; my efforts would have been best directed at the 3 million or more people out there who are simply trying to build web sites and web applications and proliferate those gnomes.

As a community, we should have been like the Web Standards Project who stuck to their guns and instead compiled a litany of examples of best current practices that everyone could have seen, understood and copied. There is no reason that developers should only now be sensitized that HTTP GET SHOULD be safe and not have side-effects.

Your first encounter with a web application or web site should have this lesson hardwired in it. The recipes that you did view source on to learn about the web (like the thousands of sites that have lifted the stylesheets from the CSS Zen garden) should have been had such practices encoded in them so that it would be second nature.

Zef Hemel (his tagline: "your daily tech snack"), who in my folksonomy is tagged with very little tongue-in-cheek as "The next Linus Torvalds" later admitted to this blindspot
But to be honest, I wasn’t so aware of the badness of using GETs for this purpose until yesterday.

All this to say that the things one thinks are obvious are often not.

The View Source imperative was crucial in how most people learned about HTML and the Web and to its widespread adoption.

As I wrote those words, I looked over to my bookshelf and saw my dogeared copy of the 1995 edition of Laura Lemay's Teach Yourself Web Publishing With HTML In A Week which should be a collector's item for all historians of science. I smote myself upside the head as I remembered how irascible young me had gotten onto this web of ours. I recalled that I first fully read the HTTP 1.1 spec in the year 2000 out of a sense of curiosity and when I saw that great dissertations were being written about the design philosophy behind it. I had heard rumours that there was much that was good in the web and like everyone had seen the daily evidence everywhere. Instinctively I had realized that some of the decisions that had been made at its formation were simply inspired and had subconsciously followed those design patterns and best practices that had been implicitly articulated. On the other hand, I had lived and written web software for 5 years with only the occasional peek at the HTTP spec to learn about things like content negotiation.

And that's the nub of the issue, who other than curmudgeons, has the time to read the HTTP spec where the importance of idempotency is prominently inscribed?

The vast majority of the world won't read long treatises. People will however copy and paste your code. Thus, in addition to good well-designed specs, we also need good samples and documentation.

Joe Gregorio's Show Me The Code tactic is the right way to go about education as is Mark Birbeck's quiet and repeated advocacy (first RSS Readers in XForms, then Google Suggest using XForms and now Google Maps using XForms). I bow down to these folks and others who are actually taking on this heavy task.

The prescient Ryan Tomayko of course was in the mix anticipating these sorts of things just weeks earlier: On HTTP Abuse
There's been a lot of good discussion around Udell's End HTTP abuse article. We need to get this figured out because it's almost embarrassing to be an advocate of standard approaches to building web applications when something as fundamental as the correct use of HTTP GET is butchered so often. Unfortunately, misuse of HTTP GET is just the tip of the iceberg. There's a whole slew of HTTP abuse going on out there (often in the form of neglect) that can be laid at the footstep of two parties: frameworks and evangelists. The frameworks suck and the evangelists aren't trying hard enough.
The small community that is coalescing around REST/HTTP should prioritize the following objectives above anything else at this point:
  1. Raise awareness of what HTTP is capable of.
  2. Fix the tools.

He then points the way to a more effective advocacy strategy namely
Can we take a page from their book? In my opinion, we're just as entitled to the phrase "Designing with Web Standards" as they are. We have a three legged stool too: HTTP, URIs, and XML. Except our stool is more like a three legged dog - you can get around but it is not quite optimal.

There is a lot more in that vein and it appears that there is a lot of soul searching among my fellow travelers. I would only add that there is also the problem that those lowly HTML Forms and Buttons are addressing. We can't afford to forget them in our efforts, indeed they might be more crucial than the rest.

The Unloved HTML Button


Thus I find myself turning back to that good friend of ours: the unloved html button.

It really doesn't get much love.

No one likes the standard HTML buttons and the other form elements. More precisely no one except users who are just trying to get on with things, and even they just see them as a means to ends that can range from awful bureaucratic process paperwork to buying that seductive, new-and-improved, ecommerce gizmo.

The first thing that Geoffrey UI Designer wants to do when he meets them is to change the appearance of html buttons. Designers just don't like them, they want to style them with cooler looking images or they want things to be hyperlinks instead. The stereotypical designers have come from the background of rich desktop applications where all sorts of interface excess has been possible. Also inevitably everyone wants to create "lickable" interfaces that make you drool. Not to be pejorative, but deep down every designer fancies themselves an aesthete ala Kai Krause or Steve Jobs and very few have looked to Web design patterns. Those Human Interface Guidelines of mundane standardization that made things like the Macintosh user interface much beloved by users everywhere are beside the point. Users might have liked them since after using just a few applications one would know how to use that darn computer thing without requiring expensive "training courses". But there was a sameness in the land and even Apple, prompted by that returned prodigal and effete Jobs, now breaks its own guidelines with increasing frequency.
"We want chrome! We want skins!", chanted the crowd as the unloved HTML button was dragged out for display.

As an application developer I like to get as close to the metal as I can and don't like having too many layers between me and the technology that I work with. Thus I often cuddle up in my midnight hours next to plain old HTML forms and buttons. In the land of the Long Tail of Application Authoring however, most people will use a framework to "program" their web site.

I would note that every web application framework has its own ideas about how forms and buttons should behave. Just in the past 6 months, the assortment of Three Letter Acronym frameworks that have been foisted on me (WCL, JSF and ODC) have each had their differing conceptions of how forms and buttons work. Needless to say, I've suffered mightily and all of these frameworks have caused much head-scratching. They leak mightily and that is because they are engaged in a war with our html forms and buttons.

In my weekend missive I inveighed, "read Joel Spolsky on Leaky Abstractions (more on that below). Let's not fight against the underlying architecture; let's understand what we're building on. The tradeoffs that were made in the complex system that is the web were not made without care."

When I got into the brave new world of XForms, I assumed that all of these lessons had been learned. Thus it was to my surprise that the first deviation from the XForms spec in IBM's first pass at an XForms Processor (on AlphaWorks) was a non-standard implementation of an image button trigger and a slider control. Now that processor was written as a guinea pig to provide input to the XForms 1.0 specification and indeed was an attempt to fit in with existing browsers. But some cunning UI designer or Framework Developer had gotten to them and they were trying, and failing I might add in these cases, to make more snappy UI widgetry within the confines of the native browser widgetry and infrastructure. Hmmm.

Now let's get concrete here ("You're so long-winded Koranteng. Boo. Hiss. Cut to the chase")

MBTA buttons




Since January 2002 and indeed just until yesterday, I haven't been able to purchase my monthly T bus Pass at the MBTA website. The web application framework that was being used in that site was only tested with Microsoft Internet Explorer. Having been true to Grandpa Netscape and Uncle Mozilla during the years in the wilderness, I would fire up the browser hoping to see a "Buy Now" button that simply never showed up in Mozilla. Thus 40 times in a row I was disappointed and tempted instead into my one monthly use of the great Internet Explorer (other of course than the frequent Windows Updates and the required testing of the products I develop). The story of Windows is of course another Book of Proverbs but that's for others to tell. I would hazard that eschatologists and numerologists everywhere would see some significance in the number 40. Presumably the Greek chorus of masses of unwashed Firefox users had more sway than my lowly monthly email missives to the MBTA tech support team about getting support for the aging Mozilla suite - again there's someone who doesn't get much love and who is being cast aside in this brave new firefoxy world.

Flickr buttons


flickr-flash-toolbar


In Flickr, I can't add a photo to a set or add a note because "To take full advantage of Flickr, you should install the latest version of the Macromedia Flash Player". Now I love Flickr, I have the greater part of the photographic record of my life on that service, but the very serious message they seem to be telling me is that they are above placing an ugly HTML button above my images. It is an affront to their sensibilities. I can understand that drag and drop organization of hundreds of photos might require Flash. But is it too demeaning to be able to simply click Add Note? It appears that they'd rather have the enhanced experience of Flash effects which can cause other issues as I've pointed out - see Cultural Sensitivity in Technology.

I can't blame them however, Gertrude and Felicia do have their seductive appeal, it does look prettier right?



Now that Buy Now button is one of those flashy mouseover-y kind of things. We're downloading 2 additional images instead of the five characters that came down with the page, slowing things up for those unfortunate to be on dial-up. There is no semantic value to the button. There's no tooltip to explain what it's for. The image doesn't have any alt text. It's less accessible wouldn't you agree? Users with different browsers had to beg for 40 months in order to be granted the courtesy to even click on it. If I had problems with my eyesight and needed to use a high contrast scheme, I couldn't leverage the operating system's built-in support for html buttons. If I had to use a screen reader, it would have been lost to me. As a developer, I would have had to write code to build keyboard navigation to the button to add tab indexes and the like. Ad nauseum.

I suppose I shouldn't complain, it is possible to style various html form elements many input or a submit buttons have lovely images. What gets me is when people don't use what facilities do exist and even worse go out of their way to avoid them.

What is wrong with a simple html button I sometimes ask?

But I lost that argument a long time ago. Indeed whenever I bring up the additional work required in the alternatives to HTML forms and buttons, since for example back in the old WebSphere Portal, I've had to clean up the accessibility and keyboard navigation messes of yore, I am treated as a wild-haired party-pooper claiming that the Emperor has no clothes. Recently I spoke of John the Baptist and Salome so perhaps this time I should say that I rather fear that a Delilah will crop my metaphorical RESTafarian dreadlocks, hence I tread carefully these days before I engage in Jeremiads...

Missing Blogger buttons


As a practical case in point of the perils of HTTP abuse, just fifteen minutes before I wrote this post, I had discovered a couple of broken links in my Best Left Unread post. Completist that I am, I was going through and adding technorati tags to my posts - the links were about the Completist Syndrome.

As a sidenote: you get a better idea of how to tag things with the benefit of hindsight. The categories or tags you place on things right after you've written something are not very good. Why is that?

Now it turns out that in Blogger's table listing of blog posts there are 2 links next to each other. Actually let's have a look at this:

2/24/2005 Edit Best Left Unread Koranteng


Let's leave aside the usability issue of why View and Delete are right next to each other. Deleting posts should typically be a rare occurence unless your former employer's lawyers object to your ruminations or more likely if the RIAA or MPAA come after you. But that's another story... Moving right along...

At 11pm, tired after a long day of work and with faulty muscle memory, I right-clicked on what I thought was the View link and opened it in a new tab. When a few minutes later, I switched to the tab I was a little perplexed by what I found. Thankfully, Blogger actually knew a little about idempotency and had a big "Are you really sure that you want to delete this post?" question with the post listed in its minor glory. But how was it possible for me to so easily get into this state? Why was it a link in the first place? I suppose that it's fair to put a trash icon next to a tag in Flickr, after all metadata is not that valuable. But a blog post?

Coincidentally, I sent the following enhancement request just yesterday to Monsieur Feinberg on a completely different issue:
Usability. At very first order right-align the "delete this post" link. In any case put it as far away from buttons that are typically used (Save and Cancel). Deleting shouldn't be a frequent activity. My own preference is to make the user have to look a little before deleting. There should be a little cognitive impedance before they delete. The system loses value when content gets deleted, let them work for it... Make them check a box and search for a button to click before deleting and make sure there's a great reason for them to do this...
Now as the Google Web Accelerator has made clear, this is not just an issue with parts of Blogger, Flickr or the MBTA. There is a fundamental problem with how people want to use forms, buttons and the user interfaces they build on the web.

HTML forms were indeed an afterthought. All the browser vendors wanted to lock you in their schemes of empire building and dreams of gold and glory. This meant that the forms that we did get were not as good as they could have been (they certainly aren't as pretty as they could be). I've gone through many midnight gymnastic sessions to try to get them to do things that Gertrude and Felicia asked. But they work, they are well known and their semantics widely understood. I would say to the my peers toiling away to fix their problem, let's tread very carefully and make sure the right lessons were learned.

Why Specs Matter and the Law of Leaky Abstractions


Your pedantic narrator actually reads and writes specifications. As you can tell, he doesn't just code or refer to himself in the third person, he can also write a lot. Indeed it is a pet peeve of his that not enough time is spent getting good specs together. Thus at this note's conception, he would write things like the following
It is sad fact of life that we don't get enough time to work on design and architecture; most of a developer's time is spent dealing with crazy schedules, task lists, status updates and the general drudgery of the "Software Process"... I was thinking about this during the rare design discussions during our meeting yesterday. So I thought I'd point out a couple of articles you might find interesting:
  • Mark Pilgrim does some of the best technology writing and also implements of a lot of cool software on the web. Here's his latest piece, a short one on Why Specs Matter. His language can be a little strong at times, but he gets the point across. You can defintely do without specs and we are often tempted to do as much; but a good spec really does make a difference. Think of XML 1.0, HTTP 1.0 and 1.1 or TCP/IP which have bred entire industries.
  • Similarly, think of 'leaky abstractions' the next time that someone tries to push their framework on you, whether it's EJB, WCL, EMF, SDO, JSF, Portlets or whatever the flavour-du-jour is. If you've ever had to spend an afternoon figuring out why the heck your tables or buttons don't do obvious things (the answer being that ultimately our output is html and no abstraction in an API can overcome the limitations of that underlying infrastructure), you'll know what I mean. Now understanding this is an argument for reducing the layers that you have in your software architecture. So for example in a case close to my heart XForms, if your underlying abstraction is HTTP, hyperlinks, XML Events and Schema and your output is HTML or some rich client UI, you should think very hard before introducing any additional layers with their own modeling and semantics since ultimately you're going to have to deal with that infrastructure. Joel Spolsky's Law of Leaky Abstractions is the final authority on that front. His canonical example is the ASP.Net framework's long crusade against my lamented HTML button.

My great friend Rob [redacted] (why don't you start a blog Rob instead of being a best-kept secret in [redacted subdivision of blue company]?) had this to say:
90% of everything is crap. That's Sturgeon's Law. Software is not excluded from this principle. We live in a mass-market, low-bid, first-to-market world. Our goal ultimately is to be less sucky than our competitors. Many of the quality things you point to, like XML Schema had amazingly long schedules, compared to our 8 releases a year, schedules so long that they could only be done by non-profits, or in a deep research group.

A written spec is key to giving an organization the flexibility to grow. Without it, adding new people to a project requires that the existing engineers take time out to bring the new members up to speed. This is the mechanism behind Brook's Law ("adding people to a late project only makes it later"). But a good set of project documentation can temper the effects of Brook's Law and provide some scalability. Imagine how much of an easier time we would have bringing new people on board, if we had a complete design doc for [redacted hotshot product].

The person in [redacted services organization] who wants to make a custom solution based on your component, the person in research who wants to use it as the base of a prototype, the co-op who wants to base a summer project on it, the lead of a new project in [redacted] who wants to reuse your code - all these people will seek information from you. You can either have a spec and a design document ready for them and be seen in a very positive light. Or you can come off looking like a fool. The difference is whether you are designing throwaway code, or code that has wings. Very little code goes far which does not have a spec or design document. You don't win an [redacted] Award for throwaway code.

Eventually we'll all move on to new challenges, and eventually active development of [redacted] will be canceled. Your code will be maintained by someone in [obvious redacted locations] who will have nothing but your spec and code to work from. And in 10 years, someone will try to revive part of your code, and without a spec, they'll be lost. Trust me, it happened to me, trying to revive parts of [redacted bemoaned product killed by monopolist] to write a [redacted useful feature] for [redacted new-and-improved hyped product]. So, if you don't write a spec, your name will be cursed in languages unknown to you in far away countries, and also by kids in middle school today when they try to figure out your code 10 years from now.

I can't add much more than that as far as development of software goes but that is sadly an unpopular perspective when it's often a case of aggressive, Real-Men-ship-code-and-batter-the-enemy warlike rhetoric (rest assured that Steve Ballmer types don't only exist at [redacted monopolist]). Sometimes a little estrogen is needed in the technology world. Further, as my own experience has shown, I know that specification-reading will likely remain an afterthought in the realm of application authoring.
View Source is the thing.

A Hyphenated Parable


I have a hyphen in my name. 2 generations back in the colonial Gold Coast, it was quite a popular thing to assert a family's identity and that is part of my story. Thus in modern Ghana you'd find many an Ofori-Adjei, Owusu-Ansah or Casely-Hayford. This assertiveness continues to this day. Naming is culturally important in my society; the outdooring ceremony of week old babies is their introduction to society and the ancestors are duly consulted so that the correct name is chosen. We pour Schnapps on the ground as the name is announced for the first time dressed as we our in ceremonial white and blue. A similar inventiveness in naming exists in those whose ancestors were 'invited' to cross the Atlantic Ocean in the past few centuries and, through various grisly legacies and traditions, I am now able to pursue 15 year searches for a certain Shaniqua who's got me woked. But I digress... In the French and Francophone traditions also, hyphens are big items: think Jean-François types. More generally in almost every culture, it is increasingly popular when people marry for a hyphen to unite the two families.

I like hyphens, they are promiscuous, sociable and attach themselves willy-nilly to all they encounter. Call me a hyphenphile if you will. It's no accident that my future wife has a hyphenated name (with the same initials no less); Freudians would say that this was a subconscious part of our mutual attraction. If we weren't patriarchal in our ethnic traditions, I might even be thoroughly modern and go for a quadruple-barreled billing for our children like Auntie Felicia.

The problem with hyphens is that well... Scratch that, let me tell you a bit about hyphens.

In computer science there is a general category of problems that have to do with delimiter characters (underscores, hyphens, colons, semi-colons, angle brackets and other special characters). Software is very concerned about structure and the parsers of our Tower of Babel file formats need to know where records begin and end. A similar issue is currently putting the tagging community into a tizzy with some favouring spaces (flickr, del.icio.us), commas (allconsuming) or semi-colons (furl) as delimiters. It's very confusing for someone who samples all these services and many an item has been mistagged by mistake.

I got my first credit-cards just as online ecommerce was picking up in the early 1990s so I have lived through the evolution of that industry's handling of hyphens.

I stopped using a certain Visa card, which was actually my introduction to Generation Debt, when it turned out that I couldn't use it for online purchases because certain backend systems couldn't handle the hyphen in my name. Circa 1999 however, this got sorted out. But that company lost the wool of the sheep I gifted to Uncle Amazon for half a decade. By and large these days, the credit card industry have fixed their issues, I am no longer forced to lose the hyphen when I order something online.

This is not the case with travel reservation systems however. The hyphen simply doesn't exist as far as they are concerned.

My very chatty travel agent was explaining all of this to me this past weekend, "The system doesn't take the hyphen. It's persona non-grata!", excited as he was to talk with someone who knew a little about the history of the Sabre system. I suspect that IBM built some of that core technology 50-60 years ago.

Most airline reservation systems handle hyphens gracefully but some don't, and, over the past few years, I've had instances where plane tickets that I thought had been purchased days earlier actually hadn't causing panicky travel agents to call me to figure out the mess so they could get their commission. I have literally lost hundreds of dollars when I've had to rebook the flights in question at higher rates. The curse of the hyphen struck repeatedly.

Thus I don't have my Delta frequent flyer number saved on Travelocity, Expedia or Orbitz. When I travel on that airline I have to remember to give my frequent flyer number at the check-in counter to get credit for mileage. As it is, I pretty much stopped flying Delta and indeed the last time I flew on Delta and gave my number, I was told that they had cancelled my frequent flyer account for non-activity... Such is life.

I booked a trip this past weekend and when I tried to check my itinerary on checkmytrip.com, I kept getting errors. I was worried and kept trying without success looking at my keyboard with bewilderment Caps Lock? No. Num Lock? No. Typo? No. etc. Then I remembered my conversation, checked my reservation slip, and realized that I had to log in with the hyphen removed from my name. Ofosu-Amaah became OfosuAmaah.

That's not the end of it however. I am regularly scrutinized by immigration or customs officials and of late, overzealous TSA officials on the lookout respectively for a certain class of economic migrant, drug smugglers and Al Qaeda splinter cells. I have always thought that my problems stemmed from the radioactive effects of carrying a Ghanaian passport, that reliable sign of economic desperation.

Another way to look at things however is that these officious officials are simply wondering if I am the hypenless person printed out on my plane ticket.

Thus they tilt their head askew as they scrutinize the face that I naively assumed soothingly said "trust me".

Hillary, when her husband's campaign made her become Rodham Clinton, chose not to use a hyphen and I think she's on to something. She may even accept campaign contributions from Delta Airlines as they struggle against bankruptcy. With some Schadefreude, I wonder if my double-barrelled hyphen boycott is having an effect on Delta.

Acela Blues


Similar fairy tales have been said about how the standards for rail gauges were developed in the US. Bob Frankston's sharp ears recently perked up when he heard about the current problems with the Amtrak's Acela trains and he speculated as follows: Acela -- A Casualty of Risk Aversion?
From the Boston Globe article on the Acela brake problems (22-Apr-2005)

Bombardier of Canada, the company that helped to manufacture the Acela, had to satisfy the Federal Railway Administration's "buy American" rules. This meant that parts for the train had to be designed for the United States. As a result, the Acela Express trains are twice as heavy as comparable European high-speed trains.

As I see it the issue is the constraints that lead to the trains being much heavier than the European trains. This is the price for risk aversion – it isn’t free. In the case of Acela trying to remove the risks by overbuilding creates its own problems and can increase the risk. Given their track record (sorry, I couldn’t resist) it seems that the Europeans made reasonable tradeoffs.

He backtracked a little with a possible correction a few days later
30-Apr-2005: Correction? A letter in today's Boston Globe noted that the heavier carriages were needed because unlike France and Japan the US trains work on existing rails. I can understand the design tradeoff between building new infrastructure and adapting to what is available. A reminder to be wary of stories that confirm ones expectations. Was it the right decision? Perhaps yes given a political climate that wouldn't accept the capital costs of a new rail line through the crowded Northeast Corridor.

And that was that you would say? But I don't think it ends there. It belies the question of why indeed the standard US railroad gauge is so different from those successfully used in continental Europe and Japan where the rail systems are models of efficiency. And this of course is fodder for historians of science and technology, train buffs and urban legend hoaxers (and debunkers alike) everywhere, nicely discussed here
The US standard railroad gauge (distance between the rails) is 4 ft 8 1/2 in (1.44 m). That's an exceedingly odd number.

Why is that gauge used? Because that's the way they built them in England, and the US railroads were built by English ex patriots.

Why did the English build 'em like that? Because the first rail lines were built by the same people who built the pre-railroad tramways, and that's the gauge they used.

Why did *they* use that gauge then? Because the people who built the tramways used the same jigs and tools as they used for building wagons, which used that wheel spacing.

[snip worryingly long 2,000+ year chain of plausible links]

So who built these old rutted roads? The first long distance roads in Europe were built by Imperial Rome for the benefit of their legions. The roads have been used ever since.

And the ruts? The initial ruts, which everyone else had to match for fear of breaking their wagons, were first made by Roman war chariots. Since the chariots were made by or for Imperial Rome they were all alike in the matter of wheel spacing (ruts again).

Thus we have the answer to the original question. The United States standard railroad gauge of 4 ft 8 1/2 in derives from the original military specification (MilSpec) for an Imperial Roman army war chariot. MisSpecs (and bureaucracies) live forever!

Now although this particular alternate history is something that many have tried to debunk, its essential appeal is that it serves as a fabulous object lesson about standards and how technology gets adopted when pragmatism and leverage is the key rule of thumb. Some things have longer lives than one would expect.

Update: Bob Franskton adds
You'd appreciate a show on the travel channel. If you take a train from China to Mongolia it goes through a stop where they change the wheel carriages for a difference in gauge and then the train moves on.

Perhaps I should ask my travel agent to book me a trip to Mongolia, I hope the rail reservations systems can handle hyphens.

Forms in Browsers


It seems to me that we have 2 ways forward to improve the experience of html forms on the web: the XForms and Web Forms 2.0 specifications.

If I were to return to my conceit, I would call them two tribes squabbling in the desert with Grandpa Mozilla feeding both sides at different times. On the one hand, you'd have the XForms buffs and there are many of them, who first saw the discord in the land: Gertrude and Felicia did have something of a point in that the Form family could be improved. Thus toiled mightily and tried to distill the kind of patterns that experience had shown were being solved in the wild.

Their advocacy problem is that they were tainted by their early association with that disreputable couple XSL and XML Schema from whom they adopted little XPath. Now XPath was a fair kid but would always be tarred by the brush of that loose XSL mother of hers. She had a few learning disabilities (or rather eccentricities) and insisted that all who entered her house take off their slippers and wear kimonos made of parentheses. Even visiting royalty, King True and Queen False from the land of Boolean were given her functional treatment.

Then there was the WHAT tribe, who were old browser calf types, now lean and mean, the stern and Operatic Håkon (screaming Howcome! Footprint! and Though shalt have no other solution except CSS and Javascript) along with latterday convert, the CSS prophet Hixie. The more pragmatic Hyatt who takes frequent Safaris may be receptive to the one but is a touch wary about how it might bite the Apple. The good Baron Brendan Eich is enigmatically philosophical about the whole thing as he nurtures the wily Firefox. Hopefully those grand viziers at the house of W3C will knock some heads together and all will learn to get along without suspicion. The jury is out for the next 18 months.

I have my hat working on the one but truth be told, I couldn't care which wins. I've pointed out some of the comprehension problems that might arise with XForms's choice of XPath see On XForms, XPath, CSS, Brevity, Syntax And More but even though I've been a heavy Javascripter I'd like to make sure that Jill Department Head doesn't have to learn script just to pull a survey together. Clearly this area remains a work in progress.

We are still in the baby years of the web, the idea is to do things right, to learn the lessons and fix problems quickly so that 50 or 5,000 years later people aren't hobbled in literal ruts about the descendants of HTML Forms.

Returning to the abuse of the buttons of my discursive tale, Phil Ringnalda devastatingly make a similar point

I wonder why buttons look like that:
(designers are looking for) an easy way of using JavaScript to tunnel their looks-like-a-GET link through POST.

Apparently in all the rush to read Section 9.1 of RFC 2616 and to misinterpret the meaning of SHOULD NOT, nobody is actually reading the part of Section 9.1 that says

This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested.

Making the fire alarm look just like a light switch isn't an example of daring and innovative design, it's just dangerous. Pushing the table out of the way won't keep you from falling off the chair.

This is exactly Tim Bray's sentiment
"I can remember like yesterday a Content Management conference about 1997, a woman from a big computer company talking about how great it was when they switched their CM system over from custom clients to the browser: "It’s so great! The browser is so limited, so they had to throw away three-quarters of the buttons and sliders and pulldowns and options, and just do it with hyperlinks and simple forms... it was so much easier to use!"

The ugly duckling user interfaces of the web have worked to a surprising extent, if we do give them the extreme makeover treatment, I hope one will still recognise their fundamental utility. I can still see traces of little Michael Jackson in the face of the current train wreck.

Placing a cache closer to the user which is what Google have attempted is simply doing what Akamai have done at a different layer. And it makes sense, caches should be as close to the user as possible, the benefits in terms of the interaction experience are obvious.

I know that down at the ground level, one might be a designing a web site and the client might want prettified links instead of those unloved html buttons. The core of web user interfaces are not sexy yet they work, and users understand them. The visual cues about what may or may not be safe are well known.

As application developers we should ask for better forms, we should be demanding of browser makers things like XForms or Web Forms 2.0 to make sure that we can go beyond the kind of stilted usability that we currently have. Our users would appreciate our efforts in that vein but for now, they know what to expect. Until then application developers should push back when we are told to "do the wrong thing".

Pushing Buttons


Micah Dubinko who was one of the chief authors of the XForms spec has it right when he calls his blog push-button paradise. That is the nirvana we're aiming for: a Garden of Eden where Forms and HTML Buttons will finally get some love. Thus as I conclude my folktale, let me give you one glimpse of our teenager button. Go ahead click on him, he won't bite, there's nothing unsafe here, a few hormones perhaps. And I know a bit about idempotency so presumably I won't lose anything.



There. That felt good, didn't it?

See also Technical Arteriosclerosis and again On The Importance of Biting Satire

Update: James Snell drops further Proverbial Zingers in Not tonight honey, I'm having idempotency issues...

Update: Holy Serendipity Batman!. Those defending Hillary in the midnight hours, no doubt through an (idem)potent keyword-searching conversational engine brew or other, happened onto my hyphenated parable. My tags are accordingly updated. I do believe this land called Blogosphere is no Kansas. I love tomorrow.

(Enough already, with the puns. Like those buttons, get on with it.)

File under: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,