The Design Is The Source Code

[refactored from DocumentationBeyondTheSourceCode]

I think we need to ask WhatIsTheSourceCode?. The opening paragraph of this thread presupposes an unhelpful answer. Let me explain. My experience is that each time I find myself picking up a pencil (or a whiteboard marker), I am experiencing a shortcoming of my development environment. By construction, I have an idea, often an aspect of design, that is difficult enough to express within the system that I feel compelled to jump outside it. And so, to appropriate one of Kent's ideas, the development system is telling me something about itself. The separation of RationalRose and all the tools like is that they are viewed, even by themselves and their creators, as separate from the system, when they are not. Perhaps we should listen more attentively to what our development systems tell us about themselves.

I'm old enough to remember when compilers were new-fangled, and developers didn't trust them. The only "real" code was machine code, or perhaps its assembler-code equivalent. In that era, in the shops where I worked, C and Pascal were viewed as programmer shortcuts to the "real" thing, and the resulting assembler-code was archived and versioned.

It took a long time and hard work for the development community to integrate the compiler into our perception of "the system", and to view the compiler input as the "source".

I argue that if we believe that objects are real, that persistent objects are real, and that patterns work, then the design (meaning the expression of the patterns and their combinations that I have modeled the solution with) is the source. So I propose to invert the XP phrase: instead of saying "TheSourceCodeIsTheDesign", I offer "TheDesignIsTheSourceCode?".

The most important decision I, as a designer, make is to model a particular situation with, to choose a trite example, a stack. Once I have made that decision, the "source code" binding in a particular language is relatively obvious. The same classes and methods recur each time I apply a stack.

Therefore, I propose that a "good" development system will let me denote my choice of "stack", and will then help me express that choice in a particular language on a particular platform. Yes, I need wormholes to cover tool shortcomings (especially in the early years) just as I need ASM directives in a good compiler if I'm doing time-critical work. I find that certain design "shapes" recur over and over; I call these "patterns".

So my argument is that we should build systems that let us express and version our design choices, in the form of a non-planar directed graph (for example). We can then traverse that graph to collect source code whenever we need it for a particular compiler. Eventually, our need for compilers will evaporate (just as our need for assemblers has disappeared) as our "source code" migrates to these directed graphs of persistent objects.

Now, TheDesignIsTheSourceCode?.

-- TomStambaugh

I agree with much of this. For many years I've thought that it is odd that software engineers don't think about the other meanings of the word 'code'. Code is something you create when you want to make something hard or impossible to read; when you want to obscure the meaning! So why do we gleefully talk about and fawn over our CODE?!

I have always been far more interested in the underlying architecture and design of a given system than the specific "code" that happens to implement it. If you offered me a choice of 100,000 lines of code, or a 10 page document with the key design, business rules, and algorithms, I'll take the latter. (This assumes I don't have to get the payroll done tomorrow; even then, I'd be more interested in the binaries than the code...) See also ThunkFactor.

-- AndyMoore

Nah, code is for communication. Cryptography is for obfuscation. For instance, Morse code is for communicating when speech is impossible. Coding (programming) is for communicating with the computer.

The last things that we edit before processing into a product are the places that accumulate our intents. (comments, changes to the original design, etc). This is what I'd label the source -- it doesn't have to be a text file (or a 'non-planar directed graph' for that matter) to qualify.

Design artifacts (produced by CASE tools or not) often require further editing, and thus further accumulation of intent, before the final set of tools are used to produce your product. This kind of thing ends up not containing your design because the intent is carried in the later edits. OTOH, some CASE tools produce things which are self contained. I would consider the 'saved state' which lets the CASE tool do this to be source as well, since they meet the criteria of being the last place we recorded our intentions. Hence, TheSourceCodeIsTheDesign.

This meandering is why I expressed a preference on AutomatedCodeGeneration for the 'Compiling' style of code generator. -- BrianEwins (who feels we are straying back to IntentionalProgramming again)

Wait a second... did you say the last place we edit before making a product is where we signify our intent?!? That seems so totally wrong-headed that I can barely respond! Changes to the design happen long before code is generated. The program code is the result of our intent to do something different. Is it not so?