Great article.

I quite regularly use state transition diagrams but I've been wondering, since I was taught UML in Uni, what on earth the Use case diagram was for! And what the Activity diagram or class diagram brought to the party that you didnt know already.

The real problem with UML though is that you draw it at the start look at it and never bother to update it as the spec changes throughout a project. About half way through the proejct you look at the UML diagram to see where to go next and you realise that your code looks nothing like the states you have put in your state transition diagram!

Chris

One of the reasons I slunk my career path down the DBA road was that I really couldn't see why it was necessary to draw complex art-work for code that was more easily digested by reading the actual procedure listing. And ERD diagrams actually made sense (maybe I'm just strange)

I'm surprised that SSADM's collection of weird and wonderfulness didn't come in for the Stob treatement - Data Flow diagrams in particular...

A truly fine article, especially the Sat Nav bit :-)

If you are using a decent tool like Together J (that has been around since 1998) or Rational XDE, then your code and class diagrams are always in synch. Anytime that you may make a change to your code, then the class-diagrams automagically update themselves.

The fact that some developers just use Visio to draw their designs and then forget all about them, is not the fault of the UML.

Secondly, "a picture tells a thousand words". You can express far more through the diagrams than you can simply by getting stuck directly into the code. If you are writing a simple "Hello World" program, then you probably don't need diagrams or documentation, but in the real world, you do. It's abit like going off and building a new Hotel without any Architecture diagrams, or Structural Drawings, compared to just building a fence in your back garden! the other useful thing about Class diagrams is that you can spot a design problem a lot easier in a diagram than you can by trawling through thousands of lines of code.

Thirdly, Use Case diagrams are partly a communication step between the Business (the people that request the software and pay the bills) and Developers. Usually, Business Analysts will create Use Cases and requirement documents. The Use Case diagrams are simply high-level representations of each Use-Case Scenario.

Forthly, no one in their right-mind ever uses Every-Single UML diagram in a project, and nor do they need to represent every single class on a class diagram. You only use what you need to express yourself. (and in all UML tools that I know, you can hide whatever classes you like from a particular representation and also limit the detail level of your class diagrams at will).

In-short then, just because you have no idea how to use UML, there is no need to complain about it. You can blame your tools all you like, but UML, like anything else is just a tool for you to use at your discretion - or not.

... except in more elegant language than I am going to use.

One might stretch the point and concede that flowcharts and their latterday bastard lovechildren had some sort of (tenuous) relevance when programs were essentially hand-written on coding sheets back in the day, there being somewhat of a disconnect between "the program" and what actually ran, ie. an object deck on punch cards courtesy of the compiler and linker which did their dirty deeds somewhere in a big air-conditioned room, the whole process having a turnaround time measured in days, if not weeks.

Then some meaningful abstraction just might have served a useful purpose as an aide-memoire. It ain't so now, and has not been the case since terminals and time-sharing operating systems replaced the card punch.

I am inclined to suspect that they remain as an empty ritual, especially beloved of those people who cannot actually read and understand the code itself. Since, as pointed out above, any design, diagram or other strategy intended to explain the behavior of a computer system to the non-techie will go off faster than a tuna sandwitch on a hot day, I really wonder why people bother with them at all. Save your money people. No matter how pretty your plans and designs or diagrams look hot off the laser printer (and they do, sometimes), your computer cannot execute them and you cannot sell them for money unless of course you are in the business of conning it out of the credulous. Which I suppose is good news for those of us who hate the idea of an id card system run by the goverment.

I invite sceptics on these points to peruse "The Mythical Man Month" by Frederick P. Brooks, jr. Flame away!

This is a rich vein, I was helpless by the end of this.

and what about nasty spiderman diagrams (to name but one) - clearly by someone who enjoyed russian dolls too much when they were young, and the many ... many others.

http://en.wikipedia.org/wiki/Nassi-Shneiderman_diagram

I once spent nearly half of a highly-paid freelance contract creating a comic masterpiece in Powerpoint, using only the included clip-art. It was epic, it was hilarious, it was inspired by Dangermouse, and it was still on the PC hard drive when my contract was terminated early and I was escorted from the building, so I've lost it.

Also, UML diagrams should be generated from code at the end of the project and stuck in the documentation folder.

The jiggly class diagram just made me spit tea on mine.

Brilliant...

There is a difference between showing what you do and showing what the data actually *is*. A state diagram shows what you do. A state diagram *can't* show what your data is.

Once upon a time there was (and still is) a language named COBOL. While it wasn't a pretty and stylish language, like our modern (*cough*) svelte (*cough* *cough*) languages like C++, Java, or C#, it was a good cloth-cap chap with a pint in its hand. So beings it had to do much without much, it had to just work harder.

And that meant looking at the data.

What was the data coming in? What was the data going out? So techniques were developed to work with data. And the techniques have found to be good again and again and again.

And lo and behold! Computers still work with data! But have we advanced design techniques? Of course not! That takes effort, and the vast majority of programmers are a pack of lazy pikers! Educators completely fail to address the concept of design. Everything has to be put in a new *language*, instead of doing well with what we have.

Now we have Haskell and F#. What do these look like? It looks like somebody grabbed Jackson Structured Programming technique and made a language out of it. Its cool to learn a new language, but not cool to learn how to design software.

Diagramming isn't design. Design may use diagrams, and it may use notation. Design is about understanding, and effectively communicating and implementing that understanding.

Now when was the last time that anything complex was communicated effectively?

At Uni our computer moduleof an engineering course still had us doing flowcharts, Nassi-Schneiderman (@Iain, I like "nasty spiderman" as a name, by the way!) data-flow diagrams (whatever the hell they were).

We were obliged to include such rubbish with any submitted course work, which of course everyone did last after completing the actual code. I thought the whole point of Fortran was that it was easy to go from mathematical formulae and translate it into a program directly (the clue's in the name, kids).

I generally like diagramming when it makes it easy to plan something out or to convey complex ideas. I use "Mind Mapping" to plan out presentations and projects. But if someone came to me with a Gantt chart or PowerPoint deck I would not insist on seeing their planning diagrams and storyboarding. These things are tools, not results in themselves. Let's treat them as such and not as sacred cows.

Hear hear to Verity.

Can anyone recommend a use case tool that allows rotation of the stickpeople for making a UML version of the Karma-Sutra?

And thanks very much for the state machine compiler tip! There does indeed seem to be a preference for tools, functions and general coolness in programming.

Ah, I am heartened to see that people are still traumatized by the old Nassi-Schneiderman charts that were all the rage when I was in college in the mid 1970s. We had one textbook that translated all of Wirth's Pascal flowcharts into NS charts, it was really clever in that a well designed NS chart had a 1-to-1 correspondence to Pascal code, the chart was unambiguously convertible into code.

This all worked fine in theory, then I got my first professional programming job. We were writing accounting software for the Apple /// in UCSD Pascal (oh what a dead end) and the designers spent all day plowing through algorithms in Knuth and Wirth books, cranking out NS charts for us lowly coders to implement. But alas, the designers were not coders and their charts rarely worked right. This resulted in continual bickering between coders and designers, as mere coders we were not privileged to alter the designers' structures, unless we could crank out our own NS charts that represented our proposed code, and the designers all agreed that our changes were correct. Sheesh!

@A. Merkin:

We use Smart Draw for diagramming at work and im pretty sure it will let you, I remember it had a rotate thingger. Unfortunatly I cannot test this right now, as I am at home, and keep UML as far away from 'home' as possible.

I've never used UML to design software but when your trying to explain designs to upper managment/clients it cannot be knocked. Although...so does powerpoint's clipart, but with UML you just look so much more cleverer.

Flow charts, context diagrams, data flow diagrams, NS diagrams - these are fine for impressing ivory-tower academics when you have to pass your semester exams. Then you take all that rubbish and toss it out of the nearest sunlight-admitting aperture.

Welcome to the real world. You have three months to get that web app up and going by the launch date, and you'd damn well better not toss two months of that stuffing around with pretty pictures! You're going to need half that time for testing and debugging anyway, no matter how thorough your design cycle nor how careful your coding. Bugs are an inevitable consequent of programming.

I swear, if one of my team dared show me one of these useless pretty pictures I'd sack him on the spot. It's said a picture paints a thousand words, but what exactly are those words? Programming is all exact words and no pictures sunshine, you can't turn a pretty chart into executable code the way you can with plain text.

In designing an application, we start with a plain-English description of the overall process, using nothing more than bulleted lists. That's for both process flow and data dictionary. Then we turn that into a HTML page where each list item links to an algorithm in pseudocode. Each line of that recurses to more detailed pseudocode where necessary, becoming less English and more C/Java/Perl/whatever with increasing recursion, and the bottom layer of the entire document tree forms the ACTUAL code we then strip out and that's our application.

It's unorthodox, it's backyard-mechanics at its best and it works a damn treat every time. The top-down methodology makes it easy to track into any code module from the root and it eases documentation building too. The higher up the doc tree you traverse, the more "laymanese" your documentation becomes, so it can be as technical or simplistic as your recipient requires, just by leveling out at a particular layer in the node structure.

We worked this technique out after years of futzing about with "orthodox" programming techniques that we found just wasted time and money. Writing the manual and the software at the same time ensures consistency and makes debugging that much easier. So no pretty pictures here, just straight translation of English into code. Done.

..this is so good, I have to give praise to Stob for saying what had to be said. Thank you, thank you, may the world listen and learn. I do still have a soft spot for Jackson's structure diagrams though because they revealed to me that programs could have structure and they help lay to rest the awful flowchart. RS.

It's the standards that are stupid. Especially UML - an overcomplex, fiddly and irritating programming language in graphical form. That's part of the problem - if there's a CASE tool that can generate code from your diagrams, then basically the CASE tool is just a compiler and you have a graphical language that has to deal with all the same issues as any other programming language, which ends up defeating the whole point of the diagram.

If you need a diagram to work something out, just do whatever works. The whole point of a diagram is to make something more intuitive - not to force people to read hundreds of pages of specifications just to figure out what it means.

Many years at college, I remember doing this thing where we compared a number of structured-programming diagram types. Of the existing ones, we ended up favoring Nassi Schneiderman - that one that divides into columns for conditionals. Only we didn't like the columns, since they got too narrow too quickly. We ended up deciding that the best idea was to use an indentation thing for all block structures, not just loops. Oh, and we reduced the boxes down to some lines down the left hand side. Basically, we ended up with pseudocode but with a load of lines down the side emphasising the indentation. We felt that even those lines were annoying and unnecessary too - but we had to maintain the pretence that it was still a diagram.

SMC looks good for state handling, but I tend to use a tool called Ragel that lets me mix regular grammar stuff with explicit state handling, and can do scanners too.

As for diagrams for documentation - that's what Doxygen and Graphviz/Dot are for. Hand drawn diagrams are almost always out of date and misleading due to maintenance. And when the diagram is generated from the code (rather than visa versa) there's much less temptation to try to encode every trivial detail in the diagram. Those inheritance, collaboration and call graph diagrams are sometimes real life-savers.

I think it's pretty much down to how your mind works.

Steve, your method of design sounds perfect to me, however I know my...shall we say, less technically^H^H^H^H^H^H^H^H^H^H^H minded, boss wouldn't stand a chance without some form of pretty picture to look at. We use a mix of State Chart/Activity Diagrams to communicate at the place I work at, and I use Class diagrams to lay out databases - but only so I have some form of paper reference to look at when I am coding sprocs/data layers.

I'm sure if one of my Uni lecturers actually looked at how I construct diagrams he would have a fit, because I know they are no way standard.

@A. Merkin:

Yup...you can...

http://www.illegalexception.com/~byte/UMLflower.gif

"...bulleted lists...for both process flow and data dictionary...turn that into a HTML page..."

well yes, I expect a simple technique would work for web applications that are no[t much] more than a series of stateless i/o transactions

is that the the first thing they learn is the syntax of the code language that they have blindly chosen to learn programming. It is also a solo effort; there's you and that infernal machine and may be a reference manual and a third-party book on the language competing for real-estate on your desk with the half-full cup of scummy cold tea and biscuit remnants. This all done in an evolutionary fashion. Design is, at this juncture, an amoeba lurking around the now itinerant programmer's mental ecology waiting a natural event to force it to evolve and become a significant factor in the survivability of our programmer. These natural events are always hard lessons.

A natural event may be the program not behaving as expected.

Is this natural event sufficient to nudge our shy amoeba to greater to complexity? Nope. Our programmer takes a sideways evolutionary step and debugs.

Debugging, the lazy and/or inept programmer's way of (not?) designing software.

Hey I like this thinks the hobbyist programmer, I'll go get a degree in Computer Science.

The programmer gets one.

The programmer now finds a job. Their line manager has given them a task which is to write code that fulfils a certain requirement, namely get this done by a so-and-so deadline. As an aside I've never met a line that is truly dead; nor have I seen a definition of this term in a business book.

So our heroic programmer writes the code and debugs as was custom as a hobbyist and as it seems to work it gets released in to that wild and unstable tribe callously named 'the users'. The line manager is pleased - I'm a good manager as I got the product out on time. He notes that he will be able to go to that programmer and ask for more of the same. The programmer obliges reinforcing the not too distinct instinct that this is how programming is done in the professional arena. The programmer gets a promotion of analyst/programmer or more pretentiously software engineer. What about that degree. learning all that so called life-cycle stuff, requirements, specifications, designs and testing? Transform analysis? Formal methods? Collar and tie job! This company seems to think it all expensive nonsense.

So what was the purpose of all that effort for my degree?

In time the programmer gets bored or more likely cynical, stressed and pissed-off.

I'm off to further my career and more money. The programmer goes to another company having gone through a most diabolical regime of IT recruitment agencies and interviews. The interview for this company included IQ test(s), coding test(s) answering questions from programmers, managers and HR people. They must be a really good company to work for to be so careful in their hiring process and I passed it! It's a good job they didn't ask about design and all that! I was a bit taken aback when they said they didn't have source control software though, when I asked about it. Must have some other great method.

The programmer sits down at their new, posh desk and starts to look at the product code. Their jaw mimics a snake's in the process of swallowing a pig. Their eyes widen in a helpless attempt to compensate for the fact that the 90cm monitor cannot widen in same manner to show a function in all its obesity even in a 2-point font. 600 lines?

After a few hours more of such an exciting and exhilarating journey the programmer then shout's to no one in particular - "Who wrote this crap?! Where's the design?!"

The amoeba stirs.

What is a design? Is it the product of designing? What is designing? What is the purpose of designing and the design?

Is code a design? Aha! The programmer's brain, latching on to this straw with all its coding and debugging might, says yes. The amoeba goes to sleep again. All is well.

The greatest challenge to any thinker is stating the problem in a way that will allow a solution.

Bertrand Russell

Is that they are almost all wrong. And yes, that certainly includes Simons stereotype of programmers.

In every field except programming, it is an accepted fact that complex designs always have errors in them. That is why prototypes are needed. And even when the prototypes have been tested, there can still be errors.

To really understand how software design relates to programming, you need to read Martin Fowlers paper "The New Methodology".

http://martinfowler.com/articles/newMethodology.html

Note the section on the separation of design and construction.

"""

These kinds of questions led Jack Reeves to suggest that in fact the source code is a design document and that the construction phase is actually the use of the compiler and linker. Indeed anything that you can treat as construction can and should be automated.

"""

The problem with programming is that the prototype looks too much like the final product. No-one is willing to admit that the only form of software design that can really be objectively validated is working source code. So you get your prototype design, you start testing and learning from it, you are ready to apply the lessons you have learnt and to refine that design (commonly known as refactoring) - but some bloody manager insists that the prototype is good enough to release.

Drawing a pretty picture doesn't make the design reliable. All it does is give people warm and fuzzy feelings. If you can't test or validate it, it simply isn't a usable design in the first place.

Also, lets not forget all those changing requirements. Do you think Boeing would cope if there new project was meant to be a passenger jet on Monday, a military fighter on tuesday, a space shuttle on wednesday and so on.

Keep hacking around a complex design, and it is bound to become a mess - irrespective of whether that design is expressed in English, legalese, pretty squiggles, or source code.

A program listing is a document that represents a software design. Compilers and linkers actually build software designs.

Jack Reeves

A program listing is a set of machine readable instructions written in a 'computer language'.

If a program listing is in C++, Java, C# et al is a design so is a listing of assembler instructions whether it has been written by a human or been disassembled from an anonymous binary.

So a hex dump of a binary in a text editor is a design?

So using Jack Reeves 'suggestion' we can conclude that:

The compiler and linker are only translating one representation of a design into another representation of the same design.

If a UML model representation of a design is a machine readable design document that can be directly translated to what a CPU can process then the MDA brigade have reached home.

It is so easy!

All that is required to 'really understand' a subject is to read a paper.

http://eyefloss.com/2006/03/04/

I didn't say you could understand design by reading that paper. I said you could understand the relationship between design and code by reading that paper.

The source code is a design document. You have a stereotype of what that belief means, but it is simply a valid way to look at the software design process. Why should an untestable and unvalidatable way of representing a design be taken as an absolute?

I never claimed that source code was the whole design. I never said that learning to code is learning design. But you have a stereotype of programmers that implies that simply because we often treat the code as a design document (whether we see it that way or not) we can't have any clue about design. That's absurd.

Truth is that most programmers have learned the limitations of the usual design documents. They too are, of course, part of a good design method, but to insist that they are accurate and complete without any real attemp to test them is just stupid. It's something that no other field of engineering would tolerate.

As it happens, I have worked in an environment dominated by hardware engineers. I was struck by how many prototype-test-redesign cycles there were. How many arguments there were about unreadable and confusing design documents. How the way those documents got that way was, essentially, from many cycles of debugging. And how, after going through all that, it would often be the software guys responsibility to work around the bugs simply because there was no time for another hardware design debugging cycle.

In other words, if you allow that the source code is a design document, you suddenly find that what programmers do is exactly the same as what engineers everywhere do. Create designs, and go through cycles of testing and refining them, sadly being forced to stop short of perfection by time and economic pressures.

Obviously a language reference manual tells you nothing about how to create a design, just as the autocad user guide tells you nothing about good design. But then, the vast majority of professional programmers know that too.

As for binaries being design representations, of course that's simply not true. Though assembler can be. The point is that a design document must contain human readable design explanations and rationales. Compiler output obviously doesn't achieve that, but any half-decent programmer spends a lot of time adding information to the source that only benefits human readers.

Of course you don't need them for piddly little programs of a few hundred lines or the odd web page. Any idiot can see that.

However, you sit down and start writing the code to control an Airbus, on your own, with no design. Not so easy is it? A good design methodology simply gives you the tools to express your ideas on paper in a manner that another engineer can understand. It is very difficult to carry the details of a large complex system in your head; it is impossible to discuss it sensibly with someone else because they will have a slightly different picture in their head.

Keeping the design up to date during the build can be difficult but is worthwhile. Some of the problems you encounter during build and testing will be design related; it is essential that these problems are resolved as a design issue, so you need an up-to-date design. That way you can make sure that when you resolve the "won't take off" problem you don't introduce a "crashes on landing" problem.

The original article is amusingly written and is a good lampoon. However, using design tools for the tasks depicted is a bit like using a JCB to bury a hamster,

I recently blogged (at http://outofthetriangle.wordpress.com/2007/07/25/learning-uml/) about finding state diagrams to be one of the most useful parts of UML and I’m pleased to see that I’m not the only one that feels this way. I also agree that, beyond a certain level of detail, diagrams cease to be useful as you might as well write code!