I Enjoy Particularly Rigorous Specs

James E. Robinson III has a confession to make:

I read specs. While sometimes messing with specs turns into a waste of time. Many times understanding the spec can keep you out of trouble. The problem is that specs are tedious, but the reality is that they have to be. Nothing is worse than a poorly written spec.
Being patient and weeding thru specifications helps you understand not just how something is designed to work, but why. I used to read specs because i had to; now i read them because i want to ... even the boring ones.

I have evolved into a spec-reading, spec-writing, specs-crazed dork during my time on the RSS Advisory Board. I now take pride in my personal compliance with RFC 2119, both in the documentation that I write and in everyday conversation. You SHOULD read it. I RECOMMEND it highly.

I used to think there was a virtue in less precise, more readable specs because they are much less intimidating to new implementers of a format. The success of XML-RPC has been driven in part by how easy the spec is to understand at first read.

But making software interoperate well is a hard job that becomes significantly harder when a spec lacks precision. An incredible amount of time can be burned on arguments over interpretation, especially when a programmer is told that his code doesn't meet a spec.

Matt Mullenweg of WordPress, a programmer so militant about web standards that he once called for a boycott of LockerGnome because it used HTML tables for layout instead of Cascading Style Sheets, recently flipped out when WordPress RSS feeds were declared invalid by the Feed Validator.

The validator had been relying on incorrect capitalization of a namespace element called wfw:commentRSS. When informed that it was wfw:commentRss instead, Sam Ruby updated the validator to follow the wfw spec.

Mullenweg, hearing from users expecting him to change his code so that their feeds passed the validator, declared that "the Feed Validator is dead to me:"

Here is a post on their mailing list which also explains the issue and includes a link to the archive.org version of the page with the capitialization everyone uses, which was there for at least two years. One line can cause so much trouble.

One line can cause an incredible amount of trouble, which is why every line in a spec has to be precise, thoroughly vetted, and developed within a framework for resolving disagreements and moving on.

I know this will sound ridiculously pedantic to programmers who are sane enough to stay away from specification development, but you have to write these documents in such a rigorous manner that every use of "should," "may", and "must" means exactly the same thing. You have to read them like a Supreme Court jurist poring over the U.S. Constitution.

An easy-to-read spec is like an adjustable-rate mortgage. You get in cheap, but you have absolutely no way of knowing how costly it will be in the long run.

Rss · Atom · 2006/05/19 · 7 COMMENTS · Link

Comments

The "flipped out" anchor's href should probably point to:

photomatt.net

#1 · Justin Watt · 2006/05/19

Do you hate a spec when companies don't follow it, even if its clear and uses all the proper 'must' and 'should' or whatnots. You a wise man Rogers, so tell us what to do. Or do you just like to say how everyone else is stuped and you are really smart.

#2 · Jim Martin · 2006/05/20

"You have to read them like a Supreme Court jurist poring over the U.S. Constitution."

I think you've just turned the RSS spec circus into an argument against the "living document" theory of Constitutional interpretation. :-)

Here's a fascinating spec-type dispute:

http://laws.findlaw.com/us/508/223.html

"After petitioner Smith offered to trade an automatic weapon to an undercover officer for cocaine, he was charged with numerous firearm and drug trafficking offenses. Title 18 U.S.C. 924(c)(1) requires the imposition of specified penalties if the defendant, "during and in relation to ... [a] drug trafficking crime[,] uses ... a firearm." In affirming Smith's conviction and sentence, the Court of Appeals held that 924(c)(1)'s plain language imposes no requirement that a firearm be "use[d]" as a weapon, but applies to any use of a gun that facilitates in any manner the commission of a drug offense."

#3 · Seth Finkelstein · 2006/05/20

True... if you're going to specify how something "should" be implemented, then different people must be able to produce similar results within their different implementations.

But we also need even more readable high-level descriptions, too. Every spec needs a muscular paragraph of text with the why, the what, the how, so that any intelligent reader can then convincingly relay the idea to others.

We need appropriate writing at both levels, implementation and ideation. Agreed...?

#4 · John Dowdell · 2006/05/20

Yes, but Matt and I made up (I explained to him why it happened, how, and by whom).

#5 · Chris Pirillo · 2006/05/20

To "Jim Martin": Your real identity is pretty obvious, given the city and ISP from which you posted.

It's a shame that you don't recognize the importance of a well-vetted spec and an open revision process, because they give users a stronger motivation to insist that companies follow standards.

When formats have open holes like the single- or multiple-enclosures question in RSS, how could anyone lean on big companies for not following the spec?

#6 · Rogers Cadenhead · 2006/05/20

I came of age during earlier Internet years when software development required you to pore over BNF syntax - not just the SHOULD and MUST, but can that field be capitalized? What constitutes a 'number'? RFC822 and the various IMAP and MIME specs were hardly light reading if you were tasked with creating software which would be used by millions of people and your bugs reported on the CBS 6:00 news.

In this sense, and particularly in response to the reference of those reddish-brown pages at Harvard - those can hardly be called a spec. But since that is what they are being advertised as, nobody can complain about any application which precisely implements what is written. Even if said application doesn't work with any other application in the world.

It is still legal.

Now the most misundertsood thing about specs is that once they are published, they are legal and binding documents *forever*. You can't go back later and say you meant it another way. The cat is out of the bag so to speak. You can create a new spec, but any application written to the existing spec is *still valid* if it claims to be valid against the existing spec. I still have many enemies over my insistence that a couple of otherwise minor changes neccessitated what is now called IMAP4rev1 because they weren't strictly compatible with IMAP4. If you implemented one to the letter, your application would be broken on the other.

Oh yeah, one of my feeds has three enclosures. I'm not going to change it either. I insist it is a legal interpretation of the spec. If somebody disagrees, show me the BNF!

Mr. Martin, which spec are you referring to? Certainly not those reddish-brown pages at Harvard...

#7 · Mike Macgirvin · 2006/05/20