Home > technical > Both Inane And Insane

Both Inane And Insane

Let’s start this post off by setting some context. What I’m about to spout concerns the development of large, complex, software systems – not mobile apps or personal web sites. So, let’s rock!

The UML class diagram below depicts a taxonomy of methods for representing and communicating system requirements.

Reqs Taxonomy

On the left side of the diagram, we have the traditional methods: expressing requirements as system capabilities/functions/”shalls”. On the right side of the diagram, we have the relatively newer artifacts: use cases and user stories.

When recording requirements for a system you’re going to attempt to build, you can choose a combination of methods as you (or your process police) see fit. In the agile world, the preferred method (as evidenced by 100% of the literature) is to exclusively employ fine-grained user stories – classifying all the other, more abstract, overarching, methods as YAGNI or BRUF.

As the following enhanced diagram shows, whichever method you choose to predominantly start recording and communicating requirements to yourself and others, at least some of the artifacts will be inter-coupled. For example, if you choose to start specifying your system as a set of logically cohesive capabilities, then those capabilities will be coupled to some extent – regardless of whether you consciously try to discover and expose those dependencies or not. After all, an operational system is a collection of interacting parts – not a bag of independent parts.

Reqs Associations

Let’s further enhance our class diagram to progressively connect the levels of granularity as follows:

Reqs Granularity

If you start specifying your system as a set of coarse-grained, interacting capabilities, it may be difficult to translate those capabilities directly into code components, packages, and/or classes. Thus, you may want to close the requirements-to-code intellectual gap by thoughtfully decomposing each capability into a set of logically cohesive, but loosely coupled, functions. If that doesn’t bridge the gap to your liking, then you may choose to decompose each function further into a finer set of logically cohesive, but loosely coupled, “shall” statements. The tradeoff is time upfront for time out back:

  • Capabilities -> Source Code
  • Use Cases – > Source Code
  • Capabilities -> Functions -> Source Code
  • Use Case -> User Story -> Source Code
  • Capabilities -> Functions -> “Shalls” -> Source Code

Note that, taken literally, the last bullet implies that you don’t start writing ANY code until you’ve completed the full, two step, capabilities-to-“shalls” decomposition. Well, that’s a croc o’ crap. You can, and should, start writing code as soon as you understand a capability and/or function well enough so that you can confidently cut at least some skeletal code. Any process that prohibits writing a single line of code until all the i’s are dotted and all the t’s are crossed and five “approval” signatures are secured is, as everyone (not just the agile community) knows, both inane and insane.

No Source Code

Of course, simple projects don’t need no stinkin’ multi-step progression toward source code. They can bypass the Capability, Function, and Use Case levels of abstraction entirely and employ only fine grained “shalls” or User Stories as the method of specification.

One Step To Source Code

On the simplest of projects, you can even go directly from thoughts in your head to code:

Thoughts To Source Code

The purpose of this post is to assert that there is no one and only “right” path in moving from requirements to code. The “heaviness” of the path you decide to take should match the size, criticality, and complexity of the system you’ll be building. The more the mismatch, the more the waste of time and effort.

  1. Shalin
    April 7, 2015 at 5:11 am

    What is the software you used to create these diagrams. Looks pretty neat. Is it creately

    • April 7, 2015 at 5:23 am

      Hi Shalin,

      Thanks for swinging by.

      I heard Creately is pretty good, but I use plain ole Microsoft Visio. Because there are no built in rules/constraints to fight against while I’m capturing my visuals, it’s been my tool of choice for as long as I can remember. Believe it or not, I use the 2003 version. I don’t need anything fancier than that – including the latest and greatest version of Visio.

  2. Phil
    April 7, 2015 at 9:34 am

    Tony’s just being humble. He’s a closet Rumbaugh, Booch, etc wannabee. Hopefully, his glorious graphical process will be documented in his new book The Practitioner’s Guide to Visual Software Construction. Did you get your advance on your new book yet Tony? 🙂

    I’d buy a copy. If you want some help with the Actors and State machine sections I could maybe help some…

    • April 7, 2015 at 10:40 am

      LOL. Thanks for the vote of confidence Phil. You’re not so wrong about the “wannabe”. I’m just handicapped by my lack of ambition (and smarts) to strive for Booch-dom. I’m just happy to share my knowledge/experience on this lil’ ole blog.

  3. April 7, 2015 at 9:39 am

    As a practitioner of Capabilities Based Planning in the DOD, http://goo.gl/B861IE the picture is inverted.

    Capabilities – Measures of Effectiveness and Key Performance Parameters
    Requirements – Measures of Peformance
    User Cases – Technical Performance Measures and …ilities

    Is the hierarchy applied in our domain.

    The capabilities provides the “ability” to do something of value. Accomplish the mission, fulfill the business case.
    The requirement is the technical or operational description needed to allow that capability to be fulfilled.

  4. April 7, 2015 at 10:35 am

    I’ve directly had to work with (design from) Software Requirements Specifications that were organized hierarchically as required capabilities, functions, “shalls” – just like the diagram. I don’t propose that the taxonomy is the only one; just that it IS one.


  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: