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.
The Gall Of That Man!
A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system. – John Gall (1975, p.71)
This law is essentially an argument in favour of underspecification: it can be used to explain the success of systems like the World Wide Web and Blogosphere, which grew from simple to complex systems incrementally, and the failure of systems like CORBA, which began with complex specifications. – Wikipedia
We can add the Strategic Defense Initiative (Star Wars), the FBI’s Virtual Case File System (VCS), JTRS, FCS, and prolly a boatload of other high falutin’ defense projects to the list of wreckage triggered by violations of Gall’s law. Do you have any other majestic violations you’d like to share? Can you cite any counter-examples that attempt to refute the law….
One of the great tragedies of life is the murder of a beautiful theory by a gang of brutal facts – Benjamin Franklin
C++, which started out simply as “C With Classes“, is a successful complex “system“. Java, which started out as a simple and pure object-oriented system, has evolved into a successful complex system that now includes a mix of functional and generic programming features. Linux, which started out as a simple college operating system project, has evolved into a monstrously successful complex system. DDS, which started out as a convergence of two similar, field-tested, pub-sub messaging implementations from Thales Inc. and RTI Inc., has evolved into a successful complex system (in spite of being backed by the OMG). Do you have any other law abiding citizens you’d like to share?
Gall’s law sounds like a, or thee, platform for Fred Brooks‘ “plan to throw one away” admonition and Grady Booch‘s “evolution through a series of stable intermediate forms” advice.
Here are two questions to ponder: Is your org in the process of trying to define/develop a grand system design from scratch? Scanning your project portfolio, can you definitively know if you’re about to, or currently are, attempting a frontal assault on Gall’s galling law – and would it matter if you did know?
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?
Visualizing And Reasoning About
I recently read an interview with Grady Booch in which the interviewer asked him what his proudest technical achievement was. Grady stated that it was his involvement in the creation of the Unified Modeling Language (UML). Mr. Booch said it allowed for a standardized way (vs. ad-hoc) of “visualizing and reasoning about software” before, during, and/or after its development.
A Bunch Of STIFs
Grady Booch states that good software architectures evolve incrementally via a progressive sequence of STable Intermediat Forms (STIFs). At each point of equilibrium, the “released” STIF is exercised by an independent group of external customers and/or internal testers. Defects, unneeded functionality, missing functionality, and unmet “ilities” are ferreted out and corrected early and often.
The alternative to a series of STIFs is the ubiquitous, one-shot, Unstable Fuming Fiasco (UFF):
Note: After I converted this draft post into a publishable one and queued it up, I experienced a sense of deja-vu. As a consequence, I searched back through my draft (91) and published (987) post lists. I found this one. D’oh! and LOL! I’m sure I’ve repeated myself many times during my blogging “career“, but hey, a steady drumbeat is more effective than a single cymbal crash. No?
The Hidden Preservation State
In the software industry, “maintenance” (like “system“) is an overloaded and overused catchall word. Nevertheless, in “Object-Oriented Analysis and Design with Applications“, Grady Booch valiantly tries to resolve the open-endedness of the term:
It is maintenance when we correct errors; it is evolution when we respond to changing requirements; it is preservation when we continue to use extraordinary means to keep an ancient and decaying piece of software in operation (lol! – BD00) – Grady Booch et al
Based on Mr. Booch’s distinctions, the UML state machine diagram below attempts to model the dynamic status of a software-intensive system during its lifetime.
The trouble with a boatload of orgs is that their mental model and operating behavior can be represented as thus:
What’s missing from this crippled state machine? Why, it’s the “Preservation” state silly. In reality, it’s lurking ominously behind the scenes as the elephant in the room, but since it’s hidden from view to the unaware org, it only comes to the fore when a crisis occurs and it can’t be denied any longer. D’oh! Call in the firefighters.
Maybe that’s why Mr. “Happy Dance” Booch also sez:
… reality suggests that an inordinate percentage of software development resources are spent on software preservation.
For orgs that operate in accordance to the crippled state machine, “Preservation” is an expensive, time consuming, resource sucking sink. I hate when that happens.
Graphics, Text, And Source Code
On the left, we have words of wisdom from Grady Booch and friends. On the right, we have sage advice hatched from the “gang of four“. So, who’s right?
Why, both groups are “right“. If all you care about is “recording the design in source code“, then you’re “wrong“…
If you’re a software “anything” (e.g. architect, engineer, lead, manager, developer, programmer, analyst) and you haven’t read these two classics, then either read them or contemplate seeking out a new career.
But wait! All may not be lost. If you think object orientation is obsolete and functional programming is the way of the future, then forget (almost) everything that was presented in this post.
Attack And Advance
Check out this recent Grady Booch tweet on the topic of “why” he, James Rumbaugh, and Ivar Jacobson syntegrated their individual modeling technologies into what became the UML standard:
Over 20+ years ago, when the rate of global change was just a mere inkling of what it is today, my friend Bill Livingston stated in HFAW that: “complexity has a bright future“. He was right on the money and I admire people like Bill and the three UML amigos for attacking complexity (a.k.a ambiguity) head-on – especially when lots of people seem to love doing the exact opposite – piling complexity on top of complexity.
Extreme complexity may not be vanquishable, but (I think) it can be made manageable with the application of abstract “systems thinking” styles and concrete tools/techniques/processes created by smart and passionate people, no?
Invisible, Thus Irrelevant
A system that has a sound architecture is one that has conceptual integrity, and as (Fred) Brooks firmly states, “conceptual integrity is the most important consideration in system design”. In some ways, the architecture of a system is largely irrelevant to its end users. However, having a clean internal structure is essential to constructing a system that is understandable, can be extended and reorganized, and is maintainable and testable.
The above paragraph was taken from Booch et al’s delightful “Object-Oriented Analysis And Design With Applications“. BD00’s version of the bolded sentence is:
In some ways, the architecture of a system is largely irrelevant to its end users, its developers, and all levels of management in the development organization.
If the architecture is invisible because of the lack of a lightweight, widely circulated, communicated, and understood, set of living artifacts, then it can’t be relevant to any type of stakeholder – even a developer. As the saying goes: “out of site, out of mind“.
Despite the long term business importance of understandability, extendability, reorganizability, maintainability, and testability, many revenue generating product architectures are indeed invisible – unlike short term schedulability and budgetability; which are always highly visible.
Unjustifiable Precision
In “Object-Oriented Analysis and Design with Applications“, Grady Booch bluntly states:
Unjustifiable precision—in requirements or plans—has proven to be a substantial yet subtle recurring obstacle to success. Most of the time, early precision is just plain dishonest and serves to provide a façade for more progress of more quality than actually exists. – Grady Booch
Pretty harsh, but wise, words, no? So, why do managers, directors, and executives repeatedly demand micro-granularized schedules and commitments from knowledge workers from day one throughout the life of a project?
- Because “that’s the way it has always been done“
- To maintain the illusion of control
- To flex their muscles and “hold people accountable” each time a micro-commitment is broken
Why am I here?
WTF?
Meh!
D'oh!
My BTC Address
Bulldozer00's Blog 