Software Reality

User Story != Use Case - but User Story != Story, Either

A user story is not a use case.

That might seem as obvious as saying "A door is not a cat", but there's enough scope for confusion - not just in the similar names - that user stories and use cases are often used interchangeably (when describing what to do next in a software project) when they probably shouldn't be.

Alistair Cockburn sums it up nicely: A user story is to a use case as a gazelle is to a gazebo.

But also:

A user story is not a story.

In other words - this is not a user story:

"The user types in a story and clicks Submit. The system publishes it to the website so that other users can read it."

It's really a use case. But it also doesn't help that there are many definitions of "use case", and many opinions on how much detail should go into one. But generally, the one consistent aspect of a use case is that it's a narrative: a description of a user's journey through the UI, and the system's responses as he clicks and types his way along: "The user does this or that; the system displays XYZ data in response. Next, the user does this... etc." In other words, the text of a use case is really a story.

A user story, meanwhile, is anything but a narrative. And this, I think, is the main source of the confusion. The name "user story" implies a story - a narrative. And it really doesn't help matters that the name is often shortened to "story". But a user story is anything but a story - at least in the narrative sense. I could see people starting to call narrative-based requirements "stories", but it's a false etymology, as they say.

'Design Driven Testing' now available as an alpha book

"Design Driven Testing", which I'm co-authoring with Doug Rosenberg, is due for release by Apress later this year.

It's a little unsettling to see chapters available so soon after writing them. But definitely a good thing.

Three chapters are available in Apress' Alpha Books programme so far... we've just submitted another two chapters for technical review, so these should land on the Alpha Book page pretty soon.

We've changed the chapters around a bit in the last few weeks. Here's the current line-up:

Part I - DDT vs TDD

1. Somebody Has it Backwards
2. Hello World Using TDD (implementing a "Login" story with TDD)
3. Hello World Using DDT (implement a "Login" story/use case with DDT)

Part II - A Walk Backwards Through the Mapplet 2.0 Project

(In this part of the book, we walk backwards through a real-life DDT project being run at ESRI Professional Services in Redlands, California. Our story begins with the completed product - code, tests, UI - and ends at the beginning, with the initial set of requirements. We demonstrate how tests were used to provide feedback at each stage of the project. The project's actually going on right now, and we're documenting its progress - meaning we're effectively writing this set of chapters backwards...)

4. Code and Finished Product
5. Detailed Design and Unit Testing
6. Preliminary Design and Behavioural Testing
7. Use Cases and Acceptance Testing
8. Test Cases and Requirements

Part III - Advanced DDT

9. Unit Testing Don'ts (Testing antipatterns)
10. Unit Testing Design "TODOs" (how to write "test-conscious" code)
11. How to write Enterprise Architect Test Case transform templates
12. When Designing for Testability is Taken Too Far

The book's also now visible on Amazon - which makes me think that I should probably get on and finish it now...

Programmer Archaeology - The perils of joining a mature project

The majority of software projects are ongoing efforts - never ending cut-and-release marathons. New screens and functions are released on (or around) specific agreed dates, but the project itself keeps on going. So it’s far more common for developers to join a project mid-flow, with its own dusty corners that no-one dares to disturb, its homegrown O-R mapping frameworks, crusted together with the foibles and wrinkles of a dozen long-since-departed self-styled code gurus.

By contrast, starting a brand new project from scratch is a rare joy: the opportunity to set the standards, consider the architecture, evaluate the available technologies given the business requirements; and to produce clean, maintainable code that’s easily unit-tested.

Ah, that last one. There’s nothing quite like the pain of joining a “mature” project and discovering that unit tests were never even a glimmer in the eyes of the project’s founding coders; the forefathers who laid the treacle-like foundations for their successors to follow.

Like a Spanish explorer in a South American jungle, you’re unlikely to find a lost city of gold; instead, prepare to discover the overgrown remnants of one long-lost programmer’s vain attempt to add unit tests - a strained nod toward provable code quality, quickly abandoned when the poor programmer was beaten back by the tangle of dependencies, the onslaught of complex constructors and static initializer blocks like Aztec ghosts sending the programmer scrambling to the far end of the jungle.

Test Smarter, Not Harder

A culture of 100% test coverage has grown up around TDD. Code quality “measuring” tools such as Clover are used as a pugil stick to beat developers over the head with, if their code doesn’t measure up to an arbitrary set of metrics: and one of these is a measure of how much product code is covered by unit tests.

(Clover does have some pretty awesome features by the way, such as test optimization; but institutionalising test coverage as a measure of code quality isn’t one of them).

TDD itself can become a highly elaborate, labour-intensive way of creating code. It’s not uncommon to end up with far more test code (which the customer never gets to see, and which arguably doesn’t really “do” anything) than product code, which is what the customer is really paying for. Yes, the customer is also paying to have product code of a sufficient quality, and that’s what TDD addresses. But there has to be a better way of improving code quality with tests: a way that doesn’t soak up developers’ time and turn the tests into the main software deliverable, in the developers’ minds.

There are three main shortcomings to TDD:

1. It’s too time-consuming
2. You end up with too much test code, with code paths duplicated by different tests
3. The final amount of test code and product code that you see is disproportionate to the amount of refactoring/evolutionary design that went on to get there

To sum these three issues up: TDD is Too Damn Difficult; it takes too much effort to produce a bit of “production code” result.

Not using TDD – just writing tests after you’ve written some code – also has problems, in particular the aimlessness of this approach. It’s difficult to know when you’re done writing enough tests – in practice there won’t be enough time to hit 100% coverage, so the team must stop at some arbitrary timeboxed stage somewhere along the road. Most dissatisfying.

So here’s the idea. These shortcomings can all be addressed by first doing a small amount of structured up-front analysis and design, and identifying which parts of the code you’ll gain the most benefit from testing. We call this approach Design Driven Testing or DDT (the linked tutorial illustrates how to use an add-in for Enterprise Architect to automate much of DDT).

Take this sequence diagram, an overview of the code path for a hotel search (click the image for the full-size version):

Design Driven Testing - New book on the way

Just what the world needs, another book on Test Driven Development (TDD)??

Well not exactly... Along with co-author Doug Rosenberg we've recently signed up with Apress to write a book about automated testing (i.e., unit testing, acceptance testing, new-kid-on-the-block behavioural testing, and requirements testing).

But... this won't be your everyday "toe the party line" automated testing volume that regurgitates the TDD doctrine. Instead, we're making the point that TDD is, to put it mildly, ass-backwards. Tests shouldn't be the sole design driver; instead the design can be used to identify the key areas of the code to cover with tests. In other words the design should drive the unit tests, just as requirements drive the customer acceptance tests.

We've found that, while it has much in its favour, TDD represents too much work for what you get out of it. For example, we definitely don't recommend that you go all-out for 100% test/code coverage, because you'll never achieve it in the time available... so what's the measure of success? How do you know when you've written enough tests and it's time to stop? Instead, we believe you should "test smarter, not harder" - in other words, identify the key areas of the code that will benefit the most from tests.

There's a chapter on Design Driven Testing in our previous book, Use Case Driven Object Modeling with UML: Theory and Practice. However, in this new book we'll be exploring in much more detail the ideas and the practicality of automated testing, using a real-world, non-trivial project ("Mapplet 2.0") being developed at ESRI for a travel website. This project will use a Flex front-end hooked up to Java server code, which in turn connects to a hotel search XML database and ESRI's ArcGIS Server. So we'll be exploring how to go about unit testing an enterprise application with a mix of languages and technologies (just like the majority of real-life projects out there).

To top it all, Sparx Systems has developed an ICONIX Process add-in for their UML modeling tool, Enterprise Architect (EA), which automates many of the steps that we'll cover in the book. You don't have to use EA to use Design Driven Testing, but after seeing what's possible with the emerging tools support for the process, we believe you'll want to!

Stay tuned, I'll post more about the ideas behind Design Driven Testing over the next few days.

20 Terabytes a Night: Designing the Large Synoptic Survey Telescope's Image Processing Pipeline

This is a fascinating new ebook by Doug Rosenberg (with some minor input from me) which provides a slice of IT history. It's written from Doug's perspective, describing how he got involved training the team producing software for the Large Synoptic Survey Telescope (LSST), and before that the Large Binocular Telescope (LBT). The bulk of the book is about how the ICONIX Process was adapted to help design the LSST's Image Processing Pipeline software. This system, and the story surrounding it, are about as geek-heavy as it gets - but as detail-rich narratives go, this one's compelling and accessible.

An OOAD method like the ICONIX Process is driven by use cases; and use cases by their nature are all about describing the interaction between people and UIs. So it's fascinating to read about how the ICONIX Process was adapted to the analysis and design of a system which consists almost entirely of non-UI components. (The result has been turned into a variant of the process called "ICONIX Process for Algorithms").

One of the biggest challenges in creating the LSST software is the sheer amount of data processing it'll need to perform when the telescope "goes live" in a few years' time.

From the book:

Lots of Brains and a Fair Amount of Time
There are a couple of things that Jeff and Tim do have working in their favor: plenty of brains (not only their own, but a widespread and largely brilliant team of astrophysicists that are experts on various pieces of the problem), and a fair amount of time (LSST is scheduled to go operational in 2015, and is currently in an R&D phase). However, it’s safe to say that most of the astrophysicists on the team wouldn’t consider themselves software engineers, although most of them are programmers. In this situation, a good strategy is to make extensive use of rapid prototyping (in this case algorithm development via prototyping) in addition to the UML modeling. So a two‐pronged strategy of prototyping and modeling has been underway on LSST for a few years now.

The LSST prototyping strategy involves annual Data Challenges (see Figure 2). These Data Challenges are development efforts with a limited functional and performance scope, and somewhat relaxed modeling requirements. During LSST’s Construction Phase, prototyping will switch to incremental development, where the actual system will be developed in a sequence of incremental releases, and somewhat more modeling will be expected.

The ebook was produced by Sparx Systems, creators of the superb Enterprise Architect modeling tool, and is downloadable for free from their website. More ebooks from Doug (again in collaboration with Sparx) are in the pipeline...

After they were (in)famous: A chat with Fangs, the Slippery Slope Serpent

Fangs made his name as the chief, multi-instance component of the Extreme Programming “circle of snakes”, discussed on-line (back in 2001), and in Extreme Programming Refactored. The idea was that the XP practices are like a ring of poisonous snakes daisy-chained together: e.g. the practice of not exploring the requirements up-front (relying instead on one-line user stories) is kept in check by a permanent on-site customer, who expands on the requirements when cornered for more details by programmers (who hunt in pairs); and so on. All it takes is for one of the practices to slip, and a snake wriggles loose. Then you’ve got an angry serpent heading your way…

In XPR we talked about how to “defang” each snake, or risky practice, to ultimately produce a version of XP that’s more rigorous while still retaining the core agile values.

But after his 20 minutes of infamy, what’s Fangs been up to since?

You must have had some fun scaring basement-dwelling programmers by leaping out at them from under their desks when their XP practices started to slip. Deep down, did you really enjoy it?

Fangs: You know, I’d really like to say no, my conscience gnawed at me like a bulimic supermodel at breakfast time. But really, there was some satisfaction to be had from seeing the practices slip, deadlines whoosh by, while coders blithely told their managers that the schedule is the customer’s problem. I mean, what do you expect? I’m a serpent.

Are you still in gainful employment?

Times are tough, I’ll say that. XP projects are few and far between these days, but they’ve been replaced by “agile”, an altogether slipperier beast. And let’s face it, agile is everywhere now… mainly because it isn’t easily defined, so anyone can choose a single practice and say that they’re being agile. It’s difficult to make a circle out of one snake. It’s terrible for my backache… and I’m not as limber as I used to be.

It’s those single surviving practices that I find fascinating.

Yes, some practices wriggled free of XP and have even become quite respectable. TDD, of course, is a pretty major one, and in many ways that’s got a circle of snakes all of its own. Then there’s user stories, which are being used more and more as a form of high-level requirements. Here’s a user story of my own: “As a salivating serpent, I want to wriggle around provocatively licking my fangs while cube-farm coders run screaming for the safety of the snack table.”

I dread to ask, but have any other XP practices escaped into the wild?

The so-called planning game has been warped and adapted in many companies. People no longer talk about gummi bears when they’re tracking project velocity, but they do estimate in terms of effort and complexity rather than time. They should try estimating me, I’m a complex beast with neuroses and misbegotten aspirations to fill several volumes of ectothermic amniote pop-psychology.

But aren’t these the stand-alone practices that could wreak havoc if one wriggles loose – and now they’re being applied individually?

Ssssscary, huh? Seriously though, what’s happening is that they are being applied selectively. The post-modern agile crowd appears to be savvier, more choosy than the original XP disciples who would strike down from upon high any who dared to voice dissent from the teachings of Beck. These days, projects are being tailored, with one practice added in at a time, rather than the original XP doctrine which was to apply everything and then, if you want to tailor the process by untying a snake, well.. good luck!

Book Review: Subject to Change

Subject to Change: Creating great products and services for an uncertain world

by Adaptive Path (aka Peter Merholz, Brandon Schauer, David Verba and Todd Wilkens)

I thought my own book took the prize for the longest title, but this one trumps it by an extra yard or two. The title evokes a sense of rapid development in “Internet time”, with requirements changing at a fundamental and product-warping level right up to the release date. A book of that sort would read more like an agile manifesto; a celebration of chaos. However, I’m happy to report that this isn’t that book.

Instead, Subject to Change provides level-headed advice on how to develop new products and services in a world that’s subject to change without notice. The key to the book’s approach is to put user experience at the heart of it all. True, there is a chapter on agile development, but it isn’t quite the gibbering chaos-monger that I’d feared.

Frameworks and the Danger of a Grand Design

In my new (more or less monthly) piece at Reg Developer, I talk about the "growing pains" that we all, as developers, tend to go through. It's the well-meaning Grand Design Syndrome, in which a developer  sees a coding problem, any coding problem, as justification to set out writing a reusable, pluggable framework. The framework "might" come in handy one day, so it has to be worth doing, right??

From the article:

"Luckily this mindset is easy to spot. Your team members will be busy creating a beautiful but over-designed system with enums, annotations, closures and all the latest language features, loosely coupled classes and several hundred pluggable frameworks when a well-placed isThisTheRightValue() method would probably have sufficed. Picture a pluggable framework that only ever has one plug."

Several commenters have questioned the part where I suggest that you probably don't want to be writing a framework at all (or even seeking out a third-party one, for that matter).

Seriously? No frameworks ever??

Not really what I meant. It's an Occam's Razor thing. In other words (applied to software design and frameworks), use something as complex and difficult to maintain as a framework if the potential for reuse is huge and obvious; otherwise, just code to the metal.

Of course, the decision of whether to write (or add in) a framework is a big one, and shouldn't be made by a junior programmer coding up one dark corner of the system (someone going through difficult growing pains), which is really the point.

Taking time to get it right == un-agile?

My latest article just appeared on Reg Developer: Hafta Man and the threat to agile design. That's hafta as in "we hafta do it this way because..."

The idea behind the article is that there are essentially 3 design mindsets:

1. We "hafta" do it this way because...
2. Wouldn't it be great, if it could work this way...
3. My grand design is just getting started!

Mindset 1. generally leads to a whole load of compromises and a project that creaks worryingly every time it moves. Mindset 2. is the opposite: a flat-out refusal to compromise on design quality, especially when maintainability is at stake.