The Code is the Design

February 4th, 2007

1. The Code is the Design

At university, most of us are taught that the development of a software should go through the following phases: requirement specification, design, construction (or coding), and testing.  By gathering system requirements (e.g. from the clients, market researches etc.), analysts would come up with a bunch of functional and supplementary requirement documents, use case model and specifications during the requirement specification phase.  Then, designers would translate these specifications into design documentations which include many diagrams (and most notably, UML) representing different aspects of the system.  These diagrams are then translated, by programmers, to the code which is compiled into software to be verified by testers before being released into production.  Depending on the particular process applied (waterfall, or iterative), a portion or all of the software would go through this life cycle at a point of time.

Because design is considered by everyone to be very important and complex (because it is the truth in any industry we know), what the university actually teaches us is to place a big focus on the diagrams, which are assumed to be the real and final output of the design process.  It teaches us to take these diagrams for granted as much as builders take building blueprints for granted.  With this perception deeply engraved into the thinking, some designers would spend most of their time elaborating the UML diagrams, thinking that they are working hard to help those poor coders to easily translate their brilliant ideas into some source code, which is considered simple to produce.  Some managers and companies would decompose their team into separate groups of designers, who do design task, and coders, who do construction task and it is almost always the case that designers are considered more senior or “high-level” citizens than their coders fellows.  No wonder why so many software projects fail…

If you are still among the people who believe that the essential output of the design process is the UML diagrams, that a bunch of comprehensive and elaborated UML diagrams would promise a successful project, and that software design and construction are similar to building design and construction, I would challenge you to think about the following questions

  • Have you ever been able to translate the UML diagram created by some other folks into some source code which 100% match with what described in those diagrams?  (First, I am not talking about Hello World, if you happen to have some UML diagrams for it :-) . Second, in building construction, it is almost always the case that the building realizes everything mentioned in the blueprints.)  
  • Have you ever been looking at a bunch of UML diagrams and say to yourself “wow, these are cool and really elaborated, they already include everything I need to do the coding task” or “this is a very complex module but with these design diagrams in place I would be able to code it really quickly”, and your thoughts turns out to be true?  (In building construction, most blueprints contain all of the details necessary for the builders to do their job.) 
  • Have you ever participated in any project which, at the end of the project, all of the two hundreds “comprehensive” UML diagrams served as inputs of coding activities are still in sync with the code?  (In building construction, there is hardly any change to the blueprint after it is finalized in the architecting phase.)

Unless you are living in the different world from mine, the single answer to all the above questions would be: NO!!!  These questions bring me to the first proposition of this post

No UML diagram is the essential and final output of the design process, the code is.  And when you are coding, you are designing.

This is a powerful concept as it helps provide satisfactory answers to many issues that we are having

  • Why can we not easily translate elaborated and detailed the design diagrams into the code as builders construct buildings from blueprints?  Why can we not code a system right the first time, regardless of the high level of elaboration of the design diagrams?  Because the coding is actually a design activity, which is highly complex and requires a lot of creativity instead of being a simple and routine effort
  • Why is waterfall process a big failure (besides conventional reasons such as lack of early feedbacks, errors take long to be detected etc.)?  Because this process erroneously assumes a design phase with an bunch of documentations and diagrams as outputs and these outputs must be locked down before coding can start while in fact designing is not done (and thus, the diagrams cannot be fixed) until coding is done.  Iterative processes allow feedbacks from later phases to shape the earlier phases, thus it is safe-guarded from this trap.
  • Why some people suggest to do just enough documentation and instead focus on what they consider more important, the code, and still be able to delivery successful products  (on the other hand, we almost never construct any building without a really really elaborated blueprint)? Because unlike building construction, in which the blueprint is the final output of the design process, in software, it is the code, not the documentation, which is the final output of the design process

You ask “well, if the code is the output of the design process, then what is the output of the construction phase that we study about”.  It is the software.  And the construction of software, unlike any other engineering disciplines, is really really inexpensive thanks to the compilers and linkers who are the “builders” in the software world and are able to take the code (blueprint) and produce the software (the building) in a matter of seconds or minutes.  Now, I assume that you are on the same page with me about the actual role of coding, let’s go a bit further on what the code actually is


2. What is the Code?

My definition of software design is: any activity that requires the application of software engineering discipline and creativity to translate the system requirements into representations which can be used as immediate inputs to some generators (e.g. compilers) to produce working software systems is part of software design.  In other words, the code is the representation of the design, not the design itself.  That also implies, the code does not necessarily mean the Java or C# source code, instead it is anything representing the design and can be used by some generators to produce working software.  In fact, if Java and C# source code can be generated from a certain specification then it is no longer considered the output of the design activity, it is then the product of the building activity.  Today, the code is expressed in Java or C#, tomorrow it may not be.  In fact, if MDA can go into the mainstream, then UML diagrams will eventually be considered the code.  That brings me to the 2nd proposition of this post

The code is anything representing the design concepts and is expressed in a format that can be used as immediate input to the software construction phase during which compilers or generators produce the working software from the code.  As a result, today, C#, Java source code is considered the code, but they may not be considered the code tomorrow


3. OK, So What Do They Really Mean To Me and Why Should I Care?

In light of the two propositions discussed in this post, let me ad
dress these questions by the following summarization

  • Because the code, not the diagrams, is the essential and final output of the design, the focus of software design is the code, not the diagrams.  Thus, although diagrams do have value, in demonstrating design concepts in a high-level view to certain audiences (clients, new developers etc.), the focus of designers should always be the code. 
  • Because the goal of the design process is to produce the code, there should be no separation line between designers and coders.  Instead, there should just be one single specie: the one who produces the code.  So, companies should immediately fire anyone who can draw very “cool” UML diagrams but cannot actually craft excellent code 
  • Today, C#, Java code etc. are considered the code, tomorrow, it may not be the same.  As a consequence of this, companies who hire people who only know C# or Java (and assume that such folks are designers) would not stand very long.  Companies should hire real designers, those who can digest complex system requirements and, through the design process, produce solutions which can address all those requirements and represent them in a format which can be used by “builders”. 
  • Real designers should not tie to any particular languages or technologies, which are meant to represent the design and will be changed over time.  Instead, besides programming languages, real designers should learn about what necessary to translate the requirements into any particular representation and that includes, but not limited to, OO design principles and patterns, algorithm design, business domains, and computing theories. 


4. A Look Into the Future

Twenty years ago, in No Silver Bullet, Fred Brooks argued that any software project must tackle two kinds of difficulties: the essential and the accidental.  While the essential is involved with the process of precisely and richly formulating abstract design concepts, which represent solutions to the system requirements, the accidental is involved with the representation of those design concepts into a format understandable by the compilers (programming language source code).  Brooks also argued that

The hard part of building software to be the specification, design, and testing of this conceptual construct, not the labor of representing it and testing the fidelity of the representation. We still make syntax errors, to be sure; but they are fuzz compared with the conceptual errors in most systems.  If this is true, building software will always be hard. There is inherently no silver bullet

While high-level languages, virtual machines, and other great tools are making the tasks of representing the design concepts easier and easier, this accidental difficulty is not completely eliminated in the current state of the industry.  As a result, it is very misleading if one uses Brooks’ proposition as an argument to say that this representation process is easy:  it should be, but not now.  And even when this is completely eliminated, we can still rest assured for the fact that the essential difficulties are still there to challenge our ability…



  1. February 5th, 2007 at 19:01 | #1

    The post has some good points: no big separation between design and code activities. Also you point out one that common fault in software development process (item “Why is waterfall process a big failure “), that is: many project managers think their project apply iterative development process like RUP. They divide into many iteration inception, elaboration, construction 1, construction 2 etc and they do not care about the architecture. The architecture is not flexible and if the client change request, they calculate the cost and set up the schedule or re-design whole system if needed. If they have in construction, they can last construction many times C1, C2, …, C10 until the requirements is stable. This is just a waterfall model covered with the RUP label.

    The second thing I agree with you is that design is not UML diagram. It makes me remember the stories when one developer is asked whether his project has design activities, he said that “none because my project is small and we do not need any UML diagram”. I have said to him that design is not only UML diagram. In fact, UML diagram only the represent of design on logical model. Before coding, you think how you organize the source files that means you are solving the dependencies among modules –> you are designing. Design and implementation is the separated concern but it should be closed as much as possible.

    It is funny that on some projects have the design team and implementation team separately. The design team only focus on draw some UML diagram and provide the responsibilities for each class but the developer only code under instruction (in this case developer just is the coder). It is not good from management purpose also technical perspective. About the management perspective, developer just is the code machine that makes them have full productivity on their works, about the technical perspective coding also impact the design. Let all developers involve in design activities is a good way that help they understand the architecture and their produced code will be better.

    However, I do not agree with you on some points. First is on the title I do not agree (it is the same while I read the same title in c2 wiki). I am the Agile supporter but just focus on code is not the good way as I think. First, I think UML diagram also is the represent of design on logical model and code is the represent of design on physical model. During implementation, one thing TA must make sure is that two representations of design be the same. So in MDA case, I do not think UML diagram is treated as code because my simple definition about code is the compiler instructions or some artifacts that guide the compiler/runtime environment can produce the result as user expect. Base on my definition, java or C# code file, XML is used during runtime are considered as code but not UML diagram because it only supports development activities not benefit to user.

  2. February 5th, 2007 at 22:40 | #2

    Thanks for your comments, anh Hai. During my internship, I used to participate in a project in which I was given some UML diagrams created by some senior folks and asked to “realize” them. The result? The output code was totally different from the design. The reason was because the designers did not provide enough of the details as well as the diagrams did not document things correctly. The point is: unless you validate your design diagrams by the code, the diagrams are useless and full of errors. Period. And that is one of the key things that makes me believe the essential output of the design process should be the code, not the diagrams – which are far from complete without having the code to back them up.

    Regarding your disagreements, let me address both of them

    1.    While I say the focus should be on the code, I also mention that the diagrams (UML and the like) do in fact have their value e.g. the most obvious value of these diagrams is their expressiveness. In fact, I would love to learn about any software architecture firstly through the high-level design diagrams instead of diving immediately into the code. However, the point is that the code is the essential output of the design process while the diagrams only help to demonstrate ideas in a high-level perspective. (As I just mention, diagrams are useless unless the code has proved otherwise.)

    2.    Think of it this way, the Java compiler’s job is to translate Java source into bytecode which will in term be JIT-compiled by the JVM into assembly code for the specific computer architecture. We do not have to write bytecode nor do we have to write assembly, they are just output of the “workers” (or “builders”) – the Java compiler and the JVM. The only code that we have to work with is Java and we call it the code. As advances in the software field allows us to express design concepts in a higher level of abstraction, e.g. UML, then it is the job of the MDA “compiler” (let’s just assume MDA can make it way into the mainstream) to generate Java or C# source code from a platform-independent model (PIM) which is possibly expressed in UML (or any other supported modelling languages). With that, we design and code in UML, not Java or C#. And thus, UML can be considered as the source code and the MDA “compiler” is actually the compiler for this language.

    Thanks again and hope to hear more opinions from you!!!

  3. February 7th, 2007 at 22:03 | #3

    First, thanks a lot for your comments, Tai.

    The point of this topic is to argue about:
    1.    Which is the essential output of the design process? Answer: the code is, not the diagrams. (Note that while the code is the essential output, I do not deny the value of intermediate output such as UML diagrams (or some sketches on the whiteboard as you mentioned) because they help bridge the gaps between requirements to the code, i.e. the design process’ final representation and offer a high-level overview to the design aspects of the software. As you say “It varies a lot but it does have a role”, I totally agree with that.)

    2.    What is actually the code? Answer: the design final representation which can be used by a compiler to produce working software. Yesterday, it was assembly, today it is Java/C# (or whatever), tomorrow it may be UML.

    This topic is not about how much design we should do. And as to your suggestion about the topic of “How much design is enough?”, I’ve already had a post about YAGNI (You Ain’t Gonna Need It) which does in fact slightly address your question). Please read and share your thoughts on it.

    The project I am working on, It has been running more than 2 years. There are 7-8 class libraries have been created with thousands of domain objects. But surprisingly, there is no design document at all. (Let’s ask aPhongBui, he knows about it; he’s joining the team to produce some more thousand of domain objects :-) ). How can they survive? Did they do the design?

    That reaffirms the proposition that: the focus of the design process is the code itself, not the diagrams. That is a live example of the fact that projects can be successful by having programmers continuously refactoring the code, separating concerns, and properly managing dependencies to make the code clean and maintainable, instead of elaborating the UML diagrams.

    On the other hand, your project sounds very interesting and I would love to know about the followings:

    1.    How complex are these objects? What domain are they in? Are they simply data (transfer) object or do they contain behaviors? Can they persist themselves or are they plain old Java/C# objects?
    2.    How are they designed? I.e., is domain-driven design applied? Are they coded in a high-level languages (C#, Java) or expressed in some domain-specific languages?
    3.    How easy is it for a new developer to jump in and maintain these objects (given the fact that there is no design diagram to start)?
    4.    Is there a high-coverage unit test suite to serve as live documentations to the objects’ API? If not, then how developers can discover the published interface of a certain object (i.e. Javadoc)?

    Again, thanks for you comments and hope to hear more feedbacks from you.

  4. thle
    February 7th, 2007 at 20:40 | #4

    So what is the point of this? In my opinion, we should not define what design really is. It just an activity we should have during software development life cycle, No matter what we produce in design phrase. The output can be some fancy diagrams drawn on the whiteboard, or can be a set of comprehensive diagrams. It varies a lot but it does have a role. The things is how we take it, spend 3 months to design and 1 month to code; or no design at all.

    The project I am working on, It has been running more than 2 years. There are 7-8 class libraries have been created with thousands of domain objects. But surprisingly, there is no design document at all. (Let’s ask aPhongBui, he knows about it; he’s joining the team to produce some more thousand of domain objects :-) )
    How can they survive? Did they do the design?

    In summary, let’s design enough, document enough, move forward, and revise the design later if it’s necessary.

    P.S. we may open a topic about “How much design is enough?”

  5. thle
    February 8th, 2007 at 16:42 | #5

    We are doing Student Information System, using VB.NET. The whole solution is nothing but 4-layers app. Since my team is only involved with the UI layer, I really don’t know how complex the business objects internally are, but I know for sure how simple for an UI dev to use their Service Interfaces. The interfaces are fine grained enough to make UI dev easy to know that he/she’s using the right interface.

    For #3, Devs that join their team, how easy to maintain those objects? It’s pretty easy as the projects already has a good framework.

    for #4. Yes, we have lot of their unit tests to use as code sample for UI team, but we only use it for complex screens.

  6. February 8th, 2007 at 17:17 | #6

    Tai, that pretty much answers the questions I have. If the object model is easy to used in the UI layer, easy to maintain even by new developers, without being designed with a bunch of UML diagrams before being coded, it does reaffirm a point I made in the original post: diagrams may be valuable for cetain purposes, but at the end of the day, what you really need to focus on (elaborating) is the code – and projects can be successful with this focus (the right focus).

  7. March 6th, 2007 at 15:53 | #7

    Buu -

    glad to see more people spreading the paradigm that software != construction ;)



  8. March 8th, 2007 at 00:10 | #8

    Yin-so, as far as I can tell, the concept is spreading quite well in the developer community, esp. when the article of Jack Reeves was whole-heartedly recommended by Uncle Bob and even included in his excellent book on OOAD (Agile Software Development: Principles, Patterns, and Practices). I would like to see the concept penetrate the management’s mind, by when I hope there would be less “architecture astronauts” and doomed projects.

  9. June 20th, 2008 at 20:51 | #9

    You are aware of Reeves’ “Code as Design”?

  10. June 21st, 2008 at 10:31 | #10

    I am. Actually I did include that paper in the References section. Thanks for informing though!

  11. December 24th, 2009 at 13:23 | #11

    Before reading this and similar articles, I did come up with the same conclusion – the code is the design, the coder is the designer.

    Coding is not a mindless practice. It cannot be mechanically generated from another kind of design presentation rather than the code itself.

  12. December 24th, 2009 at 15:15 | #12

    @Quoc Anh: absolutely, strange enough I still see walking architects taking pride on themselves for not being able to write code.

  13. September 26th, 2011 at 19:18 | #13

    What are the best graphic and web design companies to visit near Seattle Center?

Comments are closed.