I first came across the thought-provoking article What Is Software Design? by Jack Reeves as an appendix titled "The Source Code Is the Design" in the book Agile Software Development: Principles, Patterns, and Practices
In traditional software development methodologies such as the waterfall methodology, software design is an explicit phase that produces a design document as an output of that activity. The design is usually completed before coding starts. Jack takes a contrary view: the main thesis of his article is that "final source code is the real software design", and most of the article is dedicated to exploring the ramifications of this thesis. The main implication is that "programming is a design activity—a good software design process recognizes this and does not hesitate to code when coding makes sense. " And it is not just coding that is a design activity. "Coding is design, testing and debugging are part of design, and what we typically call software design is still part of design. " One may get the impression that Jack is just a cowboy coder who disdains the traditional notion of design. The following quote, however, shows that Jack values all types of design. "In software engineering, we desperately need good design at all levels. In particular, we need good top level design. The better the early design, the easier detailed design will be."
As Jack expands on the implications of the source code being the design, he clearly demolishes the assumptions behind a traditional waterfall approach to development by emphasizing the need for the design to evolve and be refined. "Eventually, we have to create the real software design, and it will be in some programming language. Therefore, we should not be afraid to code our designs as we derive them. We simply must be willing to refine them as necessary. ... All design activities interact. A good software design process recognizes this and allows the design to change, sometimes radically, as various design steps reveal the need."
Jack's follow-up article to his original 13 years later clarified his stance on design documentation beyond that of the code. "The source code may be the master design document, but it is seldom the only one necessary." But he also pointed out the flaw in insisting that this separate design documentation be a formal deliverable: "What approach they choose doesn’t matter; until someone starts insisting that these intermediate designs should be products in their own right. It’s the code that matters. If you get good code, does it really matter how it came about? If you don’t get good code, does it really matter how much other garbage you made people do before they wrote the bad code?"
These points I've quoted and almost of the articles ring true for me. I especially love the last quote – what truly matters is the code. When it is deployed into production, it does not matter how polished the design document was. In some of the formal, document-heavy client projects I have been involved with, the focus placed upon the project documentation is extreme, with the client in many cases critiquing even the grammar or punctuation within these documents. Meanwhile the code is produced with limited if any code reviews and inadequate testing. Recently on a project, after all the effort I and others put into the design document to obtain the formal sign-off by the client, I had to change part of my design after only a few days of coding. (And that is after I 'cheated' and coded a prototype during the design phase.) I discovered that another part of the design I was not involved with changed at the end of the design phase and invalidated one rather key assumption I made within my own design.
I find myself agreeing with Jack not just on the basis of his arguments, but also on the basis of my own experience. So why then are significant portions of I.T. still focused on the traditional waterfall / document-heavy approaches to developing software? Are there counter arguments I am missing? Please let me know by posting a comment, especially if you disagree with Jack and me.
If you find this article helpful, please make a donation.
The reason people still keep separate documentation/specs for software development is that code itself isn’t descriptive enough.
You can’t extract enough knowledge from code as you can from documentation. This is surely a bug in the programming languages we use.
Also, with the existing documentation you can always re-implement the requirements. If code is all you’ve got, reverse engineering of a badly implemented requirement isn’t something fun to do.
interesting…
I agree. At my college (in London), they encouraged students to heavily document each process of the development. in fact, the documentation was more important than the actual finished product.
I never actually followed the sets of rules/ document types that we were supposed to follow and concentrated more on the actual product. I just found some parts of the documentation useless. I got my project finished within a month while my class mates took a good few months.
However, I would encourage useful documentation because they can be important when somebody else has to work with it again
Jack and I are not arguing that you never need design documentation separate from the code. The main point isn’t about the documentation, it is about the nature of coding - that it is really a design activity. A corollary is that code is the final design specification, and thus that separate architecture and design documents are merely supporting the creation of the code rather than being more important than the code, as many traditionally-run projects seem to imply.
Pretty sure that book came out in 2002, not 1992, and has both Java and C++ examples.
“The Source Code Is the Design” is an XP concept. Jim Coplien, among others, has argued that more up-front design than just the code itself is appropriate in an agile approach.
@Lugnut - The book came out in 2003, but the article was originally written and published in 1992. I see that my wording in that paragraph was unclear, so I have revised it to make it clear that I am referring to the article and not the book.
Upon reflection, perhaps the title of the book’s appendix and my article is not the most accurate portrayal of Jack’s article, but I think it is fairly close. Note that I quote Jack as saying that up-front design is still important (”we desperately need good design at all levels.”)
I disagree.
Code is a way of implementing a design that fulfills the requirements of the customer.
If code = design, then there are never any bugs because of this tautology.
When delivering to the customer, the customer may never see the code - but should be able to interact and examine the design.
Without a design that is separate from the code, changes over the lifetime of the code are difficult to agree on and implement.
From the point of view of the developer, without a design all I can tell is that the code builds or does not build.
Tests are good, but they are products of the design, not the design itself.
Let’s take this the other way around…
What if we could take the design just as another coding phase? In fact, if we take the whole process of software develoment this must be so. Requirements, design, coding… are just translations of the ideas into successive forms of “code”.
Requirement gathering is a form of coding, with a syntax quite strict a lot of times. You codify the needs of the client into tables, bullet points or whatever.
Design translates that into another code, one which organizes those tables, bulletpoints or whatever into stories, use cases, etc. The language used can also be somewhat strict and it’s certainly not natural language. The design document is coded into “developer language”, a form of code “compiled” to “run” in the developer head. S/He then translates it into another code, the so called source code.
So The Design is Source Code too.
Code is too low level to convey design. Compare the size of a UML diagram to the code that implements it.
Huge difference, especially if it was a conceptual diagram.
@Venkman - that is a neat idea, but it depends on how you define code. I would define code as something that is machine-interpretable, so I wouldn’t agree that a high level design or requirements are code.
@Jeremy - I’ll tackle your points in reverse order. Regarding tests, Jack is saying that the action of testing is part of the design process. He is not saying that the tests themselves are part of the design. (I have heard some argue that automated unit tests can help with understanding the code, so it that sense they might function as part of the design documentation.)
Your other points all seem to assume that the code is an implementation or instantiation of a separate design. I agree the customer may need to see a high-level design document. But what Jack and I are saying that the code _is_ the detailed design specification. You could perhaps say that the code (as detailed design) implements the high-level design, and both levels of design need to fulfill the customer’s requirements. But I don’t agree that saying this implies there can’t be defects.
@Quick Comment - I’d agree if you said code is too low level to convey high-level design or architecture instead of just design. I didn’t mention it in my article, but in the appendix of the book Jack provided some additional follow-up remarks, one of which discussed the importance of architecture documentation. You are not the only one who seems to assume that Jack or myself is saying that separate design documentation is not needed. I’m not sure why people are coming to this conclusion, but this is not the point we are trying to make.
You’re post is pretty easy to misunderstand I guess that happens because the controversial subject, the tittle “The Source Code is the Design” but that misunderstand should be reduced by “One may get the impression that Jack is just a cowboy coder who disdains the traditional notion of design. The following quote, however, shows that Jack values all types of design” and finally killed reading the 2 Jack Reeves articles, but as you can see in every post of slashdot is more the people commenting than the ones reading all the referenced documents, so you have to be prepare to receive comments from people who read different amounts of the subject.
The more important things for me in What Is Software Design?:
1) The high level structural design is not a complete software design; it is just a structural framework for the detailed design. We have very limited capabilities for rigorously validating a high level design so coding, Testing and debugging are design validation
2) Because high level structural design is just an small definition of software design it is probably better to let the original designers write the original code (refine their design), rather than have someone else coding with only the high level structural design as guide
By the way you miss the last l in the link
http://www.developerdotstar.com/mag/articles/reeves_design.html
Good summary Basil. Have we broken ‘100′ yet of those who “get it”. Sometimes I’m afraid it doesn’t seem like it to me, but it is always nice to see someone else who does a better job of explaining it than I did.
@Jack - Thanks for the kind words! It means a lot to me to receive your positive feedback as the original author. I’m glad that I accurately reflected your ideas.