Clarity Up Front

I was skimming MichaelJackson's new book SoftwareRequirementsAndSpecifications this morning and ran across a section , named Restaurant I think, where he points out that it is possible to be unclear even in a formal [specification] language. He goes on to talk about "rough" documentation, and reminds us not to confuse our rough documentation with more complete or well-defined documentation. He even says it's OK to just throw away your rough sketches - just don't imagine that they're other than rough.

XP moves from rough to complete using intimate customer-developer contact, rough requirements, rapid design, clear code, and relentless testing:

Requirements (stories) are written on cards. (If you're retentive, it's OK to type them and paste them to cards.)
Designs are done quickly with CRC cards, and are not recorded in any permanent form.
Developers move from the CRC session to the machine, and enter the design directly in [clear] code.
Customers define AcceptanceTests that perform the necessary RequirementsTracking to show that the system does what it's supposed to do.

-- RonJeffries

Projects naturally start out fuzzy:

The GoldOwner says "we need to automate the accounting department."

We ask "what does the accounting department do?"

Then things start to get more specific.

-- JeffGrigg

Only just found this page, after ten months. Nice one, Ron. MichaelJackson has some very valuable experience of being totally baffled by the real world meaning of a vast "formal specifications", especially in telephony. It's good to see the XP view contrasted with this.

I always knew the first question I had for Michael having read the book, on the issue of rough sketches. He states boldly at the end of that section "If over 30% of your system descriptions are rough sketches either what you're doing is not that important or you're not doing it right". The very best way to interpret this, for me, is indeed to go straight from stories to code. But I couldn't resist asking Michael where exactly he got the 30% figure from, for all software projects.

Michael looked me straight in the eye and said firmly: "The 30% is correct to six significant figures".

-- RichardDrake

In this excellent book, MichaelJackson is really talking about describing the problem, not crafting the solution. The alternative to rough sketches consists of designations and definitions, description techniques for removing much of the ambiguity inherent in rough sketches. So, going "straight from stories to code" is quite a liberal interpretation of this work. However, ...

In practicing the techniques of designation and definition as taught in the book's chapters by those names, I discovered that designation is roughly the equivalent of type declaration in a programming language, and definition reminded me very strongly of writing C Language macros. So, you may not be far off in making this connection. I have yet to read TheSourceCodeIsTheDesign (forgive me, there's a huge backlog of XP stuff at this site and I'm only nosing around a month or so), but I have reason to believe that in some cases and to some extent TheSourceCodeIsTheSpecification.

By the way, MichaelJackson's son DanielJackson, who is now teaching at MIT, is doing some very interesting work in lightweight formal methods in which rather abstract object models can be quickly written and checked automatically. The language is called Alloy and its compiler is called Alcoa. You can read more about them (or download the tool and play with it) from: http://sdg.lcs.mit.edu/alcoa/

-- WaldenMathews

TheSourceCodeIsTheDesign and the UserStoriesPlusUnitTestsAreTheSpecification? may be closer to the "strong XP" view, Walden. But thanks very much for the tip about DanielJackson's interest in lightweight formal methods.

-- RichardDrake

You're welcome. I want to point out a similarity between what Daniel Jackson is doing and the XP approach. With Nitpick or Alcoa, you "specify a little, check a little...it's fun". [roughly quoting Daniel from one of his papers] The similarity is in the immediacy and concreteness of the feedback. What's surprising is the number of mistakes even a good specifier makes simply trying to describe a system with desirable properties. How's that for ClarityUpFront?

-- Walden