What Is Software Design

Other than being an interesting question, it is also the title of an article by JackReeves. The article is available at http://www.bleading-edge.com/Publications/C++Journal/Cpjour2.htm. See also TheSourceCodeIsTheDesign.

See also WhatIsSoftware (a more basic question)

Years ago I read an article that completely changed how I thought about software design. I hope that ExtremeProgramming picks this up because I see it as a very insightful view which ExtremeProgramming completely validates empirically. For me, it couldn't have come at a better time. When I first read it, I was effectively post-documenting a project using IEEE software documentation standards and cursing the incredibly surreal waterfall process.

The name of the article is What Is Software Design? It was written by JackReeves and published in The C++ Journal Vol. 2, No. 2. 1992. I think the journal is defunct, which is a shame. I really wish everyone had a chance to read the article. [...not to be confused with the "C Users Journal" (now the "C/C++ Users Journal") at http://www.cuj.com/ ]. [See above for a link to the article -- TheEditor]

Essentially the point is this. When the original phases of software development were laid down, they were just plain wrong. Requirements, Design, Implementation, and Test are not what we think they are. Design is not something that you do only before you code. Implementation is not the act of coding. We can see this if we look realistically at what they are in other engineering disciplines.

(from the article):

The final goal of any engineering activity is to create some kind of documentation. When a design effort is complete, the design documentation is given to the manufacturing team. This is a different set of people with a different set of skills from those of the design team. If the design documents truly represent a complete design, the manufacturing team can proceed to build the product. In fact, they can proceed to build much of the product without further assistance from the designers. After reviewing the software development life cycle today, it appears that the only software documentation that actually seems to satisfy the criteria of an engineering design are the source code listings.

This is how people build bridges and buildings and toasters. See also: AnalogyBetweenProgrammingAndManufacturing

Think about it. When you are programming, you are doing detailed design. The manufacturing team for software is your compiler or interpreter. The source is the only complete specification of what the software will do. The cute boxes in class diagrams are not the design, they are a high level view of the design.

What are the ramifications? (paraphrased from the article)

Software runs on computers. It is a sequence of ones and zeros. Software is not a program listing.
A program listing is a document that represents a software design. Compilers, linkers, and interpreters actually build (manufacture) software.
Software is very cheap to build. You just press a button.
Software is expensive to design because it is complicated and all phases of the development cycle are part of the design process.
Programming is a design activity; a good software design process recognizes this and does not hesitate to code when coding makes sense.
Coding actually makes sense more often than believed. Often the process of rendering the design in code will reveal oversights and the need for more design effort. The earlier this happens, the better.
Testing and debugging are design activities - they are the equivalents of design validation and refinement in other engineering disciplines. They can not be short changed.
Formal validation methods are not of much use because it is cheaper to build software and test it than to prove it.

-- MichaelFeathers

Something's been nagging at me about this page for along time. I don't believe that the article says The source code is the design, as the XPers would have us gloss it. What the article seems to me to be saying is: the kind of document that a source code document is, is "design".

That, yes, but more. The source code is also the ONLY document in whatever collection you may have that is guaranteed to reflect reality exactly. As such, it is the only design document that is known to be true. The thoughts, dreams, and fantasies of the designer are only real insofar as they are in the code. The pictures in the reams of UML are only veridical insofar as they are in the code. The source code is the design in a way that no other document can claim. One other thought: maybe gloss isn't in the writing, maybe it's in the reading. -- RonJeffries

The source code might have code that is never executed, variable and procedure names that are lies, and is in general a poor way to learn the programmer's intention. To me, design is as much the decisions and the reasons as the results of the decisions. Sometimes code makes that clear, but usually it doesn't. -- RalphJohnson

A common problem on these various "The XXX Is The Design" pages is that "design" is both a noun and a verb. And the noun "design" can refer to a document, or it can refer to the process that lead up to creation of the document, or it can refer to a mental model that one conceives by examining the software and/or talking to the people who built it, or a conceptual model used to explain the software workings to others. People are confusing all these meanings, all of which are "right" in some contexts but "wrong" in others. -- KrisJohnson

I've read this article before and agree with its most significant point. The only serious quibble I have with this is the part:

: ''Given that software designs are relatively easy to turn out, and essentially free to build, an unsurprising revelation is that software designs tend to be incredibly large and complex ... [snip] ... We have long since passed the point where simple software is of much interest. Typical commercial software products have designs that consist of hundreds of thousands of lines.

In my experience, this is just not true - much of software development is in IT applications. And these, more often than not, are well-known problems whose solutions must be customized to the business for which the code is written. This includes almost all web applications. And the tools for writing these kinds of applications, such as j2ee and .net, keep expanding.

The problem with software engineering is that it treats software as if it were conceptually complex. For most of us this isn't true. I can honestly say that of all the projects I've been associated with in my career only a distributed programming framework would qualify. The complexity of most software comes, rather, from the number of details that must be managed.

And, to complete the point, a significant number of those details represent decisions on how to handle errors and other unusual conditions. I once read that 40% of the lines of code in the typical program handles errors. That would match my experience.

Which leads to my critique of most of the current generation of design tools - they really don't help in managing details, particularly handling errors. They are more effective at modeling the logically correct paths through the system. This is usually a simple problem for which modeling is most often not necessary. Notice the number of trainers and other modeling experts who recommend modeling only the parts you 'need' to - i.e. where the problem is conceptually difficult or where the logically correct path itself contains too many details.

In a holistic way, this parallels my critique of software engineering methodologies including the current generation of agile methods. They deal primarily with developing new software treating maintenance as a special case. But if my experience is any guide, maintenance is the general case. I've certainly worked on many more > 1.0 versions in my career. Very few methodologies, from waterfall to rup to agile, are effective for the typical job of enhancing an existing application. You are just rarely in the position of being able to architect/design from scratch.

Perhaps this explains my partiality to extreme programming. It is the only methodology IMNSHO that addresses key maintenance issues - DoTheSimplestThingThatCouldPossiblyWork, OnceAndOnlyOnce, RefactorMercilessly, TestFirstProgramming, and so on.

Enough rambling on a Saturday night. -- HowardFear

moved from TheSourceCodeIsTheDesign

Since this topic seems to be generating some interesting discussion (still) I have posted the original article on the web at http://www.bleading-edge.com/Publications/C++Journal/Cpjour2.htm. I am thrilled that someone is finally looking at this. To me, the entire software industry has a serious quality problem. However, as WilliamEdwardsDeming has repeatedly shown, the only way to really improve quality is to modify the process. In order to modify the process, you have to first understand it. -- JackReeves

"The final goal of any engineering activity is to create some kind of documentation."

This confuses me more than the average thing, all of which confuse me. I would have thought that the final goal of software engineering was to produce the program. Is this just another proof that there isn't any such thing as software engineering? -- RonJeffries

His formulation is confusing because we use the word documentation differently. Consider engineers making a bridge. They make plans (which he calls design documents) and hand them to the construction team building the bridge. EE's make schematics (which he calls design documents) and hand them to the techs with soldering irons. We make source code (which he calls design documents) and hand it to the computer which manufactures software. The parallel is striking. We are just the first branch of engineering that had a way to go directly from design to product at the press of a button. Building, or implementation, is so easy in software that we overlooked it and called programming implementation. We forget that every coding decision is a design decision which impacts the capabilities of the product. -- MichaelFeathers

I would argue that the purpose of a bridge design is not documentation, nor even a bridge, it is to get people and things to the other side of the river. The purpose of a software effort is not documentation nor a program, it is an aid for people trying to accomplish a task. -- WayneMack

The purpose of the bridge design is not to get things to the other side of the river: it is to show a bridge-builder how to build a specific bridge. The purpose of the bridge is to get things to the other side of the river.

In software, it's the same. The purpose of the software design is to show a software-builder (e.g. compiler) how to build a specific program. The purpose of the program is to help people accomplish a task. -- DougKing

How does one separate the design from the use? How does one design a "bridge" if the purpose is not to get things to the other side of the river? How does one know whether the design is prepare to handle the vehicle weight, the vehicle volume, the river width, etc., except in the context of use? How does one even know that the design results in a "bridge" rather than a coffee table? Design is subservient to use. -- WayneMack

I'd have to agree with WayneMack here, and refer back to RalphJohnson - Since the end purpose is to help the users accomplish their tasks, and the code doesn't always reflect the programmer's (or the architect's) intent 100% clearly, it's essential to have some kind of design documentation that both the programmer and the customer agree on. Speaking as someone who's rarely had to design new stuff, and most of the time ended up maintaining either 20-year-old legacy code or new stuff where the developers have already ridden off cackling into the sunset leaving tumbleweed rather than documentation, it puts you in a strange position when your employer doesn't want to have you make changes or enhancements for free, the customer's saying "But it's not doing what it's supposed to!", and you're caught in the middle with no way of proving anyone right or wrong. My ideal would be to have all the use cases or stories available and hopefully a fitnesse test suite that both sides have signed off. -- MattMoran

Isn't this a bit polarized? The main problem that I see with the arguments on this page is that it fails to see the spectrum from design to product. If you want to be a stickler about the term product, then you really have to consider the runtime 1s and 0s as the true end-product. A compiler doesn't fit this bill when considering dynamic libraries. Not only that, but you may be using a code generator. The idea of There is just one product is flawed. There are intermediate products as well.

Likewise, I argue that there are intermediate designs. Perhaps a given company has it set up that once the requirements people laboriously figure out how this software is going to be used and what comprehensively constitutes what needs to be in the program, they produce the design document, the requirements doc. That then is handed off to the manufacturers, the coders, to figure out what brands of wood they will use, the screws, etc... that they will use to implement the blueprint. They produce what was required. Why can't this Big Design First model work? Perhaps we don't know how to train good architects/engineers/designers yet.

This doesn't mean some critical (design) decisions aren't made by bridge builders if the designers didn't do a good job. I framed houses for a while and sometimes a blueprint is confused or brain dead. But to say that this occurrence necessitates that we call house framers architects may be stretching it.

But my main point: it isn't just design and product, it's design <-------------> product, with many intermediate stages along the way, to whose view, a point directly to the right may seem like product, and the point directly to the left may seem like design.

I like the direction the writer is taking this discussion, but believe we need to go a step beyond. "Design" and "Product" are not two end points of a continuum. There is a constant change in the way things are done, and we hope that the improvements outweigh the degradations. It is a mistake to try and take a snap shot of time, identify the approach in use at that time as "a product" and presume it must have been preceded by "a design." The reason we have software is to bring us closer to the ideal of having a constantly adapting, constantly evolving tool. Software development should not be modeled on approaches that were restricted by high production costs that necessitated a slow iteration cycle and a slow learning curve. The learning curve in building bridges has taken literally hundreds of years, while the same learning curve can be accomplished with a software program in weeks.

I think the comparison between manufacturers and coders by using the example of screws does not suite very well, because the screw in the area of software development is actually more the kind of keyboard or monitor which will be used by the coder. Beside this, most software developers are probably not aware about the amount of detail which is necessary to design e.g. a bridge, especially when it comes to the mathematical models used for the static calculations (which are part of the design phase). This level of detail is absolutely comparable to source code. So there is no Big Design First Only model even in classical engineering. Every engineering design phase consists of both a rough overview respectively estimation and a very(!) detailed low level design phase. -- BernhardPollak

"Essentially the point is this. When the original phases of software development were laid down, they were just plain wrong."

Well, according to my Software Engineering book ...

The term "WaterFall", and the whole concept of phases, was introduced by ProfessorBoehm. He produced the idea after comparing software "authoring" with more traditional engineering practices, most of which use the WaterfallModel. Less than six months later, he actually retracted the idea saying that his article was trying to introduce the idea of a life-cycle, not any particular model. By that time it was too late.

The WaterFall model may be flawed, and hard to maintain, but the reason it is famous is because any model is better than no model at all. Thus, being the first one people heard of, they tried it first. The irony is, that is was never really intended to for use in software.

As for throwing the whole design thing out, and just designing in code... Hahahahahahahahah no really Hahahahahahahahah :)

Another good article that brings out the problems in comparing software development to manufacturing or civil architecture is at http://domaindrivendesign.org/articles/blog/evans_eric_software_is_not_like_that.html

Some systems analysts maintain that source documents are unnecessary. They say that all input can be entered directly into the system, without wasting time in an intermediate step. Do you agree? Can you think of any situations where source documents are essential?

Any time you have to make an early decision. This happens when you have to define what a product is and is just as important a step as any line of code.

All "source documents" are essential, otherwise they would just be "documents"! But no document is incontrovertibly a source document: ultimately, the river has no source, but is the rain falling on the hillside, is the sun shining on the sea.

The original "What Is Software Design?" essay has been republished in developer.* Magazine as part of a new set of three essays titled "Code As Design: Three Essays by Jack W. Reeves." The other two essays in the set are a new essay titled "What Is Software Design: 13 Years Later" and the original, previously unpublished, letter to the editor that Mr. Reeves sent to C++ Journal. Instead of publishing the letter, the editor asked Mr. Reeves to turn it into an article, which he did. The original letter stands up quite well as an essay in its own right and is well worth a read for those interested in these ideas. This page is the introduction page for all three essays: http://www.developerdotstar.com/mag/articles/reeves_design_main.html

CategoryDefinition