Archive
Working Code Over Comprehensive Documentation
Comprehensiveness is the enemy of comprehensibility – Martin Fowler
Martin’s quote may be the main reason why this preference was written into the Agile Manifesto…
Working software over comprehensive documentation
Obviously, it doesn’t say “Working software and no documentation“. I’d bet my house that Martin and his fellow colleagues who conjured up the manifesto intentionally stuck the word “comprehensive” in there for a reason. And the reason is that “good” documentation reduces costs in both the short and long runs. In addition, check out what the Grade-ster has to say:
The code tells the story, but not the whole story – Grady Booch
Now that the context for this post has been set, I’d like to put in a plug for Simon Brown’s terrific work on the subject of lightweight software architecture documentation. In tribute to Simon, I decided to hoist a few of his slides that resonate with me.
Note that the last graphic is my (and perhaps Simon’s?) way of promoting standardized UML-sketching for recording and communicating software architectures. Of course, if you don’t record and communicate your software architectures, then reading this post was a waste of your time; and I’m sorry for that.
Annoying And Disappointing
Atego’s Artisan Real-Time Studio, Sparx’s Enterprise Architect, and IBM’s Rational Rhapsody are big and expensive UML modeling tools. You would think they support all of the basic visual modeling elements of the UML, no?
On the left side of the figure below, I show the four fundamental, visual UML symbols for conjuring up (wrong, incomplete, and inconsistent) structural views of an object-oriented software system in the form of class diagrams, deployment diagrams, component diagrams, etc.
It blows BD00′s already incoherently twisted mind that Artisan Studio doesn’t provide visual elements for a UML Node or a Component. As can be seen on the right side of the figure, the work-around is to use stereotyped Classifier elements to fill the void. It’s annoying and disappointing, dontcha think?
But hey, not many people (especially extreme left-wing agile zealots) buy into the potential of the UML for shortening the development time and long-term cost of big, sprawling, long-lived software systems . So, “meh” to this irrelevant post.
Note: I’m a relatively newbie user of Artisan Studio. If you’re an advanced user and you know that I’m mistaken here, then please speak up and tell me how to find these two seemingly-hidden buggers.
Irritated
Unsurprisingly, one of BD00′s posts irritated a reader who stumbled upon it. For some strange reason, BD00′s scribblings have that effect on some people. In the irritating post, “The Old Is New Again“, BD00 referred to Data and Control Flow diagrams as “old and obsolete“. In caustic BD00 fashion, the reader commented:
Use Cases and Activity Diagrams, in contrast (to the Data Flow diagram), offer little guidance in effective partitioning. They rely upon the age old “sledge hammer” approach to partitioning” (ie, just break-er-up any way you can). Sledge hammer partitioning is what cave men used to partition entities. So in a critical sense, DFD’s are new and hip, while Use Cases and Activity Diagrams are based upon logic that is older than dirt.
BD00 likes all visual modeling tools – including the DFD hatched during the heyday of structured analysis. BD00 only meant “old and obsolete” in the sense that DFDs pre-dated the arrival of the UML and the object-oriented approach to system analysis and design. However, BD00 did feel the need to correct the reader’s misunderstanding of the features and capabilities that UML Activity Diagrams offer up to analysts/designers.
Both the DFD and UML activity diagram pair below equivalently capture an analyst’s partitioning design decision (where DFD Process X == Activity Diagram Action X). Via “swimlanes“, the lower activity diagram makes the result of a second design decision visible: the conscious allocation of the Actions to the higher level Objects that will perform them during system operation. So, how are UML activity diagrams inferior to DFDs in supporting partitioning? A rich palette of other symbols (forks, joins, decisions, merges, control flows, signals) are also available to analysts (if needed) for capturing design decisions and exposing them for scrutiny.
DFDs and UML diagrams are just tools – job performance aids. Learning how to use them, and learning how to use them effectively, are two separate challenges. Design “guidance” for system partitioning, leveling, balancing, etc, has to come from somewhere else. From a mentor? From personal experience learning how to design systems over time? From divine intervention?
Broken, Not Bent
It’s one thing to “bend” the UML to express a design concept that you don’t know how to express with the language, but it’s another thing to “break” it outright. By “break“, I mean drawing old-school, ad-hoc, single-symbol diagrams that all look alike and passing them off as UML class, deployment, activity, etc, diagrams.
By propagating broken UML diagrams out into the world in a sincere, but fruitless, attempt to establish a shared understanding among team members, the exact opposite can occur – mass confusion and an error prone, friction-filled development effort. Even worse, presenting the ad-hoc quagmire to customers and financiers who have a rudimentary education in object orientation and UML can cause them to question the competence of the presenters and the wisdom of their investment choice.
But hey, there’s nothing to worry about. Nobody understands or cares about the UML anyway. Thus, the ambiguity, inconsistency, and conflicts inherent in the design won’t be exposed (or ever traced-back-to) if schedule and cost disaster strikes.
All models are wrong. Some, however, are useful. – George E. Box
Related articles
- Proprietary Extensions (bulldozer00.com)
- UML Tool for Fast UML Diagrams (allincircles.wordpress.com)
- Mind Maps: The Poor Man’s Design Tool (drdobbs.com)
Proprietary Extensions
When using a tool or technology that implements a universal standard, beware of inadvertently using non-standard extensions that “lock” you into the vendor’s revenue stream.
The graphic below shows a screenshot from Artisan Real-time Studio version 7.2. Even though the tool implements the UML 2.0 standard, notice that there are several “non-UML” diagrams that you can create: “Constraint Diagram“, “General Flow Diagram“, etc. If you choose to create and use these proprietary extensions, then you’re sh*t out of luck if you get pissed off at Atego and want to port your model over to a different UML tool vendor with a better and/or less expensive solution. D’oh! I hate when that happens.
I’m not trying to single out Atego here. Every commercial vendor, especially of expensive tools, bakes-in a few proprietary extensions to give them an edge over the competition. The sneakier ones don’t annotate or make obvious which features are proprietary – so beware.
Monopolistic Providers
In search of economies of scale, centrally planned and controlled economies in nations and corporations tend to create monopolistic providers of goods and services. For example, in corporations, accounting, personnel, and R&D departments are usually deliberately organized as subsidized monopolies. They are subsidized in the sense that the users of their products or services do not pay for them directly; the supplying units are supported financially by funds that are allocated to them from above. The pool from which these funds are drawn is filled by a “tax” allocated from above to the units served. Monopolistic units that are subsidized are generally insensitive and unresponsive to the users of their services, but they are sensitive and responsive to the desires of the higher-level units that subsidize them. These higher level units are even more removed from the units served than the serving units. As a result, they are often unaware of, or unresponsive to, the needs and desires of the internal users of monopolistically provided goods and services. – Russell Ackoff (Ackoff’s Best: His Classic Writings on Management)
OK, time to practice my “bent” UML modeling skills and test your understanding with the class and sequence diagram pair below. The class diagram provides a structural view of a fictional Ackoffian system. The sequence diagram steps through an amalgam of behaviors in a world where monopolies rule. Any questions, comments, critiques, accolades, WTFs?
The Scrum Sprint Planning Meeting
Since the UML Scrum Cheat Sheet post is getting quite a few page views, I decided to conjure up a class diagram that shows the static structure of the Scrum Sprint Planning Meeting (SPM).
The figure below shows some text from the official Scrum Guide. It’s followed by a “bent” UML class diagram that transforms the text into a glorious visual model of the SPM players and their responsibilities.
In unsuccessful Scrum adoptions where a hierarchical command & control mindset is firmly entrenched, I’ll bet that the meeting is a CF (Cluster-f*ck) where nobody fulfills their responsibilities and the alpha dudes dominate the “collaborative” decision making process. Maybe that’s why Ramblin’ Scott Ambler recently tweeted:
Everybody is doing agile these days. Even those that aren’t. – Scott Ambler
D’oh! and WTF! – BD00
Of course, BD00 has no clue what shenanigans take place during unsuccessful agile adoptions. In the interest of keeping those consulting and certification fees rolling in, nobody talks much about those. As Chris Argyris likes to say, they’re “undiscussable“. So, Shhhhhhh!
Scrum Cheat Sheet
While reading Schwaber and Sutherland’s official Scrum Guide, I decided to concoct a graphical UML-heavy cheat sheet of the monstrously famous agile framework.
Scrum Framework Components
System Class Diagram
Scrum Roles
Scrum Events
Scrum Artifacts
Human_Being:preserveSelf
As the UML sequence diagram below shows, an “unnamed” Nature object with an infinite lifeline asynchronously creates and, uh, kills Human_Being objects at will. Sorry about that.
So, what’s this preserveSelf routine that we loop on until nature kicks our bucket? I’m glad you asked:
Have a nice day! 
The Old Is New Again
Because Moore’s law has seemingly run its course, vertical, single processor core speed scaling has given way to horizontal multicore scaling. The evidence of this shift is the fact that just about every mobile device and server and desktop and laptop is shipping with more than one processor core these days. Thus, the acquisition of concurrent and distributed design and programming skills is becoming more and more important as time tics forward. Can what Erlang’s Joe Armstrong coined as the “Concurrent Oriented Programming” style be usurping the well known and widely practiced object-oriented programming style as we speak?
Because of their focus on stateless, pure functions (as opposed to stateful objects), it seems to me that functional programming languages (e.g. Erlang, Haskell, Scala, F#) are a more natural fit to concurrent, distributed, software-intensive systems development than object-oriented languages like Java and C++; even though both these languages provide basic support for concurrent programming in the form of threads.
Likewise, even though I’m a big UML fan, I think that “old and obsolete” structured design modeling tools like Data and Control Flow Diagrams (DFD, CFD) may be better suited to the design of concurrent software. Even better, I think a mixture of the UML and DFD/CFD artifacts may be the best way (as Grady Booch says) to “visualize and reason” about necessarily big software designs prior to coding up and testing the beasts.
So, what do you think? Should the old become new again? Should the venerable DFD be resurrected and included in the UML portfolio of behavior diagrams?
Why am I here?
WTF?
Meh!
D'oh!
