Source Code Is Elements Not Design

There's a line of thought that says TheSourceCodeIsTheDesign. Instead, think of source code as analogous to elements. Everything is made out of elements. Yet when we want to understand how someone is feeling or how the brake system of a car works we don't hand them a periodic table.

Code is the lowest level of detail and does not reveal intent or purpose. Even with clever names, somebody coming off the street still won't know the program. "Then look at the unit tests," someone says? What are they testing for?

Look at the UseCases to understand that. Where do the use cases come from? The customer. So without understanding the customer on down you will not be able to understand the source code.

So the source code cannot be the design. Source code is the elements out of which customers make their solution, but is not the end in itself and therefore cannot represent the design.

However, there is a community of developers, many of whom read these pages, that aspire to use the lexical and abstraction capabilities of modern computer languages in such a way as to transcend the elemental aspects of code. They have found refactoring (changes that improve the intention revealing aspects of the code without changing its behavior) to be a useful activity and spend many words here trying to get better at it. They are to be encouraged.

"Code is the lowest level of detail and does not reveal intent or purpose."

Do detail engineering drawings reveal intent? They are still the detailed design of the part specified by the drawing.

I don't think so. The whole system must be considered the design. No single part describes the whole.

"Source code are the elements out of which customers make their solution, but is not the end in itself."

The design drawing is not the end in itself, source code is not the end in itself. Factories and craftsmen turn the drawing into a useful thing. Build scripts and compilers turn the code into useful systems.

Agreed. There's a lot more to it than picking out one part and saying that's it.

[Disagree. Build scripts and compilers are just mechanisms for turning the source code into executables, which aren't even required in interpreted systems. The source code is the distillation of the rules of a system into a set of instructions the machine can follow.]

"Code is the lowest level of detail and does not reveal intent or purpose."

Not my code. My code expresses multiple levels of detail, from top level use cases down to the order of bytes on a network. Source code can express any level of abstraction. Well written source code reveals intent and purpose.

"Source code are the elements out of which customers make their solution, but is not the end in itself."

None of my customers make their solutions out of source code. Instead they pay me to make their solutions. I express those solutions as source code.

-- EricHodges

Yes, Eric, you express those solutions as source code. The source is not the solution, your design is. The source is what comes out of your design in a format that can be converted into instructions for the machine to follow. Eh?

The source code is how I represent a design to a compiler. We could argue about the "existence" of an Platonic ideal form of the design, but that would be wanking. As far as the compiler and customer are concerned, the source code is the only design that matters.

A compiler is not taking a design and making an executible. It is taking a detailed machine description and translating it to another machine description. The compiler doesn't care how the code is organized, named, what it does, or anything else.

FalseDichotomy. My source code is both a design and an automatically translatable description of a solution. It can be understood by the compiler(s) and other humans. It is the humans who care how the code is organized, named, etc. This isn't an either/or situation.

"Code is the lowest level of detail and does not reveal intent or purpose."

I do not understand this statement. Original author are you trying to say "can not", "should not", or "must not"? Clarify your point so that we might discuss it.

''Does not is correct. The design is in the whole system, not just one part of it. In your list i would go for can not because the part is not the whole, and whole is the design. Assuming WhatIsDesign. If you did not have the customer and use cases the source code would not express intent and purpose. Much like if you see a spiral stair case in a building you don't know why it was chosen or its true place in the overall scheme. Much like in the small code snippet the idea of anonymous contributer would be lost if the context was lost.''

[But code can express anything a use case can express. Since code can use natural language it has all of the expressive ability of natural language. I don't think anyone is arguing that a code snippet is the entire design, rather that the complete code is the complete design.]

Let's do an experiment. You should be able to take a complex system, which are the only problems that matter, and perform the inverse operation of creating the use cases. Let's use linux. Do you think you would come up with the original list of use cases? I would say no. Reasone one: The customer is central to XP because they are necessary to clarify issues. This role does not end because you have source code. If the customer were to die there would be no one to perform that role. If the customer is not needed then XP does not need a customer. Reason two: a system is the result of hundreds of interacting use cases. Use cases do not map 1-1 to code. The same function may be involved in numerous use cases. Unless the you are a big fan of the implicate order, inverting these back to the original use cases would be very difficult in the general case.

Much like ghosts i will not believe it can be done until i see it. I have worked over many many code bases and have never seen such a system. I would like to see examples if you have them.

[I never said the source code to Linux was the design. I said my source code is the design. You can see the use cases in my source code. They are spelled out in English. They convey the same information conveyed in source code or plain text. You don't have to implicate order or invert anything. The use case is spelled out. Give me any use case and I'll show you the equivalent source code. -- EricHodges]

Then please show us one of your projects and let's see. An individual use case is not interesting. What is interesting are large complex systems that have evolved over time with many developers touching the code.

[I don't own the source for any of the large projects I've written. Show me a software design or design element that can't be expressed as source code. You said "If you did not have the customer and use cases the source code would not express intent and purpose." I can prove that to be false by showing how any use case can be expressed as code. Any intent or purpose you write in a use case can be (and should be) written as code. The use case defines requirements. The source code is a design for software that meets those requirements.]

Since you are asserting it can be done the proof is on your side. It's always convenient that source code is never available to help prove that it can be done. And of course its written as code. That doesn't mean you can go from the code back to the intent. Much like you can't go back from your DNA to you.

[You're asserting it can't be done. I do it. Why should I believe you? What is it about design that can't be communicated between humans via source code?]

Yet you can't show one shred of proof other than your assertions. I believe you think you can do it. I believe your code is probably good. What i don't believe is that it communicates everything you think it does. Why? Because i can't do it and i have never seen it done. In the scheme of things vi is a simple project. How about write a vi a clone as a test? Not just a function. Not just a couple of functions. But a complex system.

[How does that back up your assertion that source code is not design?]

My test SourceCodeIsDesignRequiresInversability. Without a demonstration of this for a reasonably complex system all i see are repeated assertions about source code is the design.

[You make the same assertion on SourceCodeIsDesignRequiresInversability as here. You claim source code isn't expressive enough to show intent and/or purpose. I see no evidence that source code can't be as expressive as natural language text. That doesn't mean all source code shows intent or purpose, just that there's no reason it can't.]

Re: Linux source code

The source code, even of Linux, is the design. If it can't show intent, then it's not a particularly good design, but it is the design nonetheless. Here's an even simpler test: If you change the document, does it change the system when it is rebuilt? Change the use cases all you like, change the comments in the code, change the UML paper diagrams and whiteboard scribblings, change the requirements specification; hit the compile button, and you end up with the same system. Change the code on the other hand.... Change the blueprints for a house, and when the next house is built from those blueprints, it will be different from the first. Change the letter written from the client to the architect, where the intent of the second floor balcony is expressed, it doesn't matter; if the blueprint isn't updated, that balcony won't be built, regardless of how intent the client is. What's the purpose of this extra heavy-duty wiring in this back room? Does the client intend to install a tanning bed or a marijuana garden? It really doesn't matter to the builders, they just build the damn thing, because that's what the design tells them to build.

Re: Show me your source code.

Show me yours.

Please, we're professionals above all else. Asking us to show you our source code is unprofessional. If you want to see some good source code, look at JavaUnit.

Oh, and by the way, the only way to construct a person is via the DNA. Whether we as humans understand the connections from DNA to body part is a different matter; nature understands it just fine. The DNA is the design for the person.

Please, we're professionals above all else. Asking us to show you our source code is unprofessional. If you want to see some good source code, look at JavaUnit.

In other fields when someone makes a claim like TheSourceCodeIsTheDesign it must be proven and peer reviewed. That would be considered professional. That you think we can throw around arguments all day without any evidence in the form of source code is just sad. JavaUnit is very simple. Even then many of the programmers we have are confused by JavaUnit and do not find it at all transparent. Then you will say something like "get new developers" because only idiots can't understand JavaUnit. Then i would say the programmers are fine, it's the code that isn't as clear as you think it is.

Does any engineer have to prove that 'the blueprint is the design'? And anyway, that's academic, not professional. A professional has legal obligations to his copmany and/or client not to divulge source code. Get a job and find out for yourself. About the only way you're going to get to see source code is from an open-source project.

Which brings me back to JUnit. Yes, it is very simple. In fact, it is remarkable how simple it is. That's why so many people use it, and why it has so many side-projects which extend it, and why it has been ported to so many other languages (I myself have ported it twice). Any other automated unit testing framework would probably be ten times more complicated, have many more bugs, and be ten times less useful. Would source code that is ten times more complicated be something worthy of analyzing its design? No. Not if the same thing could be accomplished with a simpler design. The reason JUnit is so simple is because it has a good design, a SimpleDesign. If KentBeck and ErichGamma worked on your complicated source code, I'm sure it would end up looking very simple indeed.

If you can't understand the code -- and I don't see why you can't, especially if you've examined the tests -- then may I suggest that you brush up on your code reading skills (or use a good IDE like IntellijIdea or EclipseIde to help you navigate the code), because reading UML diagrams is fun and easy, but it doesn't tell you what the system does. The only thing that can do that is the code, which is why the source code is the design. All the rest is just (possibly incorrect or out-of-date) documentation*.

Now of course you're going to exclaim something or other about onus of proof or whatever, but I challenge you this: Show me some JUnit code that isn't clear in its purpose or intent. There are only ten framework classes, it shouldn't be hard to find if it's there.

[* Which is not to say that documentation is bad, just that it isn't the design.]

To find out what sparked the idea TheSourceCodeIsTheDesign, read WhatIsSoftwareDesign.

JavaUnit is very simple. Even then many of the programmers we have are confused by JavaUnit and do not find it at all transparent. Then you will say something like "get new developers" because only idiots can't understand JavaUnit. Then i would say the programmers are fine, it's the code that isn't as clear as you think it is.

I wouldn't say "only idiots can't understand JavaUnit", but I would say anyone who can't understand JavaUnit isn't a Java developer. One of the principle requirements for developing large or complex software in a given language is the ability to read code written in that language.