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 The article was written in 1992 so ignore the references to C++ (I mentally translated them to Java) and instead focus on what Jack is saying about the nature of design in software development. I recommend starting with the summary at the end of the article.

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.

Tweet

If you find this article helpful, please make a donation.