As engineers, we all "design" artifacts (buildings, programs, circuits, molecules...). That's an activity (design-the-verb) that produces some kind of result (design-the-noun).
I think we all agree that design-the-noun is a different entity than the artifact itself.
A key activity in the software business (indeed, in any business where the resulting product artifact needs to be enhanced) is to understand the "design (the-noun)". Yet we seem, as a community, to be pretty much complete failures at recording it, as evidenced by the amount of effort people put into rediscovering facts about their code base. Ask somebody to show you the design of their code and see what you get.
I think of a design for software as having:
- An explicit specification for what the software is supposed to do and how well it does it
- An explicit version of the code (this part is easy, everybody has it)
- An explanation for how each part of the code serves to achieve the specification (e.g, a relation between spec fragments and code fragments)
- A rationale as to why the code is the way it is (e.g., why a particular choice rather than another)
What is NOT a design is a particular perspective on the code. For example [not to pick specifically on] UML diagrams are not designs. Rather, they are properties you can derive from the code, or arguably, properties you wish you could derive from the code. But as a general rule, you can't derive the code from UML.
Why is it that after 50+ years of building software, why don't we have regular ways to express this? (Feel free to contradict me with explicit examples!)
Even if we do, most of the community seems so focused on getting "code" that design-the-noun gets lost anyway. (IMHO, until design becomes the purpose of engineering, with the artifact extracted from the design, we're not going to get around this).
What have you seen as means for recording designs (in the sense I have described it)? Explicit references to papers would be good. Why do you think specific and general means have not been succesful? How can we change this?
[I have my own ideas that flesh out the bulleted viewpoint above, but I'm interested in other people's answers... and its hard to implement my scheme [[and maybe that's the real problem :-]] ]
EDIT 2011/1/3: One the answer-threads hints that "documentation" (presumably textual, in particular not-formal) might be adequate. I guess I should clarify that I don't believe this. CASE tools appeared on the scene starting in the 80s, but the early tools mostly just captured pixels for the diagrams of whatever you drew; while the tools were arguablly commercially successful, they really weren't very helpful. A key insight was, that if the additional "design" artifacts are not formally interpretable, you can't get any serious tool help. I believe the same insight applies to any long-term useful form of design capture: if it hasn't got a formal structure, it won't be of any real use. Text documents pretty much fail this test.