This is a second entry about
Rereading Mythical Manmonth. You can read the first one
here.
When I started programming, I never used to create '
detailed flow charts' while many people (usually who are not actively coding) urged it. I did create some small flowchart to get overall picture in my mind but never detailed flowcharts. Later same thing happened with UML diagrams, I always felt little guilty about it. Till I read, Fred Brooks observations about Flow charts.
These are the Fred Brooks observations about Flow Charts in section named '
Flow Chart Curse' (in essay 15, The Other Face).
The flow chart is a most thoroughly oversold piece of program documentation. Many programs don't need flow charts at all; few programs need more than a one-page flow chart.
....
The detailed blow-by-blow flow chart, however, is an obsolete nuisance, suitable only for initiating beginners into algorithmic thinking.
....
In fact, flow charting is more preached than practiced. I have never seen an experienced programmer who routinely made detailed flow charts before beginning to write programs. Where organization standards require flow charts, these are almost invariably done after the fact. Many shops proudly use machine programs to generate this "indispensable design tool" from the completed code. I think this universal experience is not an embarrassing and deplorable departure from good practice, to be acknowledged only with a nervous laugh. Instead it is the application of good judgment, and it teaches us something about the utility of flow charts.
Try replacing the '
Flow chart' in the above discussion with '
UML Diagrams' and the whole discussion now suddenly seems very recent discussion. In my experience 'UML Diagrams' are more preached that practiced and most of the time these diagrams are created 'automatically' from the code at the end of development cycle.
Obviously with UML also, I create a few class diagrams and sequence diagrams to clear top level picture. But I don't create very detailed UML diagrams of every single class and function. In my experience, when a team tries to create very granular UML diagrams :
- it confuses every one in the team,
- it takes too much efforts
- and hence not really worth it.
However, many times Customers and internal
SEPG groups ask for UML diagrams (sometimes because of mostly misguided notion that a UML documented design means 'good design', sometimes because of everybody is doing it, sometimes because of all the UML hype).
Still I could never clearly explain why UML is not a 'silver bullet' in documenting software design. That is till I reread the '
No Silver Bullet' and the section '
Essential difficulties->Invisibility'.
Software is invisible and unvisualizable. Geometric abstractions are powerful tools. The floor plan of a building helps both architect and client evaluate spaces, traffic flows, views. Contradictions become obvious, omissions can be caught. Scale drawings of mechanical parts and stick-figure models of molecules, although abstractions, serve the same purpose. A geometric reality is captured in a geometric abstraction.
The reality of software is not inherently embedded in space. Hence it has no ready geometric representation in the way that land has maps, silicon chips have diagrams, computers have connectivity schematics. As soon as we attempt to diagram software structure, we find it to constitute not one, but several, general directed graphs, superimposed one upon another. The several graphs may represent the flow of control, the flow of data, patterns of dependency, time sequence, name-space relationships. These are usually not even planar, much less hierarchical. Indeed, one of the ways of establishing conceptual control over such structure is to enforce link cutting until one or more of the graphs becomes hierarchical.
In spite of progress in restricting and simplifying the structures of software, they remain inherently unvisualizable, thus depriving the mind of some of its most powerful conceptual tools. This lack not only impedes the process of design within one mind, it severely hinders communication among minds.
Since software is inherently 'unvisualizable' (as explained above), software developer will always feel that any graphical modeling technique (Flow charts, UML Diagrams, Swimlanes, data flow diagrams, etc etc) is insufficient to imagine and communicate the software design.
So in conclusion:
- Software design is hard.
- Documenting and communicating software design is even harder.
- Flowcharts, UML diagrams or any other diagrams are not a silver bullet of 'design documentation'.
- Most likely, there will never be a 'silver bullet' in design documentation.
UPDATE (Oct 30, 2010):
I fully agree that UML diagrams are useful communication tool to document/discuss/understand the overall design. However, it utterly fails as 'documentation' tool for documenting every class and function. Documenting every single class with UML results in information overload. So I agree with observations of
Stephan.Schmidt and others.
In one of the project that I worked, we had about 10 different modules. Each module had some 2/3 key classes. We created module dependency diagram. We documented the class hierarchy (inheritance and aggregation relationships) of these classes in a single class diagram. We also documented names of various design patterns used in these classes. Then we documented key functions of these modules with 2/3 sequence diagrams. This documentation served us well. New team members can quickly get the hang of the system and start contributing.
At the end of the project, our customer insisted on UML diagrams for every single class and function. Hence we reverse engineered whole system and created UML documentation of every single class. It was completely incomprehensible and hence completely useless.
