The Source Code Is The Detailed Design
The Source Code Is The Detailed DesignOpening Statement
This page is a reduction of the views in TheSourceCodeIsTheDesign which implies that the design of a software product (or system) can only be of interest, and therefore understandable to programmers who understand the source-code. The position here is that too extreme of an allegiance to TheSourceCodeIsTheDesign is almost a polite F.U. to all other ProjectStakeholders who are not programmers. It quietly removes them from the design process since, if they cannot write code, how can they contribute to the design?
As an alternative, we present TheSourceCodeIsTheSpecification. Here, we use specification to mean the functional specification or low-level, detailed design of the implementation. Source code, especially today, is high-level enough, quickly prototyping enough, and fluidly recompiled quickly enough that a detailed-specification is no longer needed. Literally, the source-code has replaced, and taken the place of, the detailed specification. These are specs, we are not talking about requirements here.
Problems with viewing the Source-Code as the Design
TheSourceCodeIsTheDesign is a programmer-centric view of the overall system. All ProjectStakeholders that cannot read code are disenfranchised from the design process. Furthermore, viewing the source-code as the only design artifacts adversely impacts maintenance and QA programmers, especially those that are new to the project. It forces a sink or swim attitude on them: Here's the design (which also happens to be the source-code), if you can't figure it out, too bad. It requires even QA engineers (who want to chart various states throughout the system or error-handling, to be as good at understanding code as the software developers. Our view is that a few high-level design artifacts can provide ProgressiveDisclosure for would be programmers and QA engineers on a project.
Well then, what the hell is the Source-Code?
While the source code does not replace the need for high-level design include some high-level artifacts, it does replace the need for detailed specifications that provide low-level plans for the system implementation. In fact, one of the worst things one can do is to create some high-level designs and then spend a bunch of time creating detailed specifications based on those designs that describe how the design should be implemented! This does not imply the design and architecture wont change during implementation. SystemMetaphor, high-level design, and specification (i.e. programming) can all happen collaboratively and asynchronously. If the design is high-level enough it is not often affected by refactoring but neither should it be resistant to change. However, it is important to note that the high-level design does not model the source code, it models the major and public interactions and connections of the system. On the other hand, specifications or low-level/detailed design are always effected by each small change in the source code. Nowadays, if you do need a descriptive non source-code artifact representing the specification, it can be almost always generate from the source using a tool like Genitor or JavaDoc.
Therefore, the source code should be the specification without replacing the high-level system design. Specifications usually turn out to be worthless as they are completely redefined the very moment that coding starts. The reason this happens is because the source code 'replaces the specification in actual use.
Therefore, don't create detailed specifications on paper but allow the source code to specify the system. If you do need a document version of the specification, dynamically generate it from the source code using a tool like JavaDoc.
But, design should model the system and not its implementation. The design lives below the SystemMetaphor but above the specification (i.e. the source-code). It models the major roles, responsibilities, and interactions in the system without naming individual classes or their methods.
If a design is found to be affected by each time the specification (source-code) is refactored, then this is an indication that design was not modeled at a high enough level of abstraction. Somehow, the designer ended up modeling the source-code instead of the high-level solution. Strive for a high-level design that is not greatly impacted by language choice. This is another quantifier that can be used to discover if a design is at the correct level of abstraction.
TheSourceCodeIsTheDesign is a natural response to the fact that most designs are too low level and act more as specification than design. After all, a blueprint isn't a design, it is a specification. TheSourceCodeIsTheSpecification is a natural response to TheSourceCodeIsTheDesign being used to justify the absent of a high-level design (such as patterns, CrcCards or UML diagrams) that is above the source but below the SystemMetaphor.
Discussion:
I take "specification" here to mean the requirements, what is wanted. If that's correct, the specification must be independent of the source code, or else every program is 100% correct and 100% what the customer wanted. This is false to fact.
A specification is distinct from the requirements. The requirements live in the ProblemDomain while the specification details the implementation of the SolutionDomain. Specification, as it is used here, means the detailed functional specification. Today's languages are more high-level, they don't take days to compile or need to imprint themselves on physical cards that need to be sequenced or resequenced if an error is found. We do not need the detailed plans we once did prior to implementation. Languages today specify the behavior of the system by themselves. No other low-level, detailed specs are needed. However, high-level design that fits somewhere between the SystemMetaphor and the actual source-code is still required in large and complex systems. This is why "we" say TheSourceIsTheSpecification? but it is not the design.
TheSourceCodeIsTheDesign points out that the source code is the ultimate arbiter of what is actually in the system. No other document is definitive in that regard - the source code is.
(I still think you are confusing "design" with "functional specification".)
Marks: 100% for first paragraph. Say NO to this WikiPage! (Only kidding. Unless somebody really wants to ahem ... clarify a bit by er ... condensing this or that.) 70% for the second cos although what it says is 100% true it slips over whether it's wise to use "design" only to mean "ultimate arbiter of what is actually in the system". Surely not. Walden's point at the end about the Wiki usage bending the meaning of the original article is interesting too.
A specification for what?
I'm not sure I understand. I suppose the same thing as the design.
The system?
Well, now we are getting somewhere... Design decisions are often wrong. But the design describes the generalized solution (roles, interactions, patterns) and not the implementation of those solutions. Problems in the design, and there will be many, should be effected by System changes, not source code changes or refactorings. Remember the difference between rewriting software and refactoring software. Refactoring changes how something is done and not what it does. What it does would reflect a change in the system requirements (i.e. UserStorys) which would, as a result, impact the design. It wasn't the source-changes that impacted the design, it was the change in or reinterpretation of requirements. If we are actually changing what the program does then we are not refactoring. If we are not changing what the program does, then it should not impact the design. If it does, than we have designed at the wrong level of abstraction. We are being redundant by expressing low-level designs sufficiently expressed by the code. -- RobertDiFalco
Is design formal or informal? If it is formal, then is code. It isn't source code because it is currently not wedded to your parser.
Is it not a design decision to break a class into a TightGroupsOfClasses [sic] or to leave it all in one class? To choose a hash table over an array? If it is, not only is your very high level design is inadequate to express all design in the system, but almost all the code embodies some of the design.
Remember, it is still refactoring provided the system maintains functional equivalence. If the internal structure changes wildly, yet still produces the same output to the same input, the system is still "refactored." -- AnonymousDonor
Yes, I do remember that. Since the system design is only interested in the functionality it is not affected by source code changes that do not change functionality. I would go back to what I said about roles versus classes. This sort of refactoring does not change the roles, so the design is not effected. -- RobertDiFalco
Is it not a design decision to break a class into a TightGroupsOfClasses [sic] or to leave it all in one class? To choose a hash table over an array
Actually, I don't think it is, at least not in the sense I am speaking of....not the system design. These have to do with how the design is specified or implemented. The system design is more interested in larger issues such as is the system distributed or single user. Does it require parallel processing? Change is these will require changes in the design. Using a merge sort instead of a insertion sort do not. For me, the friction you describe above is in the specification not the design. For me, I would specify in the design that I was going to use a hash table over a lookup table. These are choices that may affect the implementation of the design but nots its functionality. I'm still struggling with exactly how this looks in my head so some of this may be inaccurate but I think it gets closer than the traditional view of TheSourceCodeIsTheDesign. -- RobertDiFalco
I understand now. Yes, I agree with you that the system architecture/design (*) is unaffected by source code decisions. How could you refactor in or out a SQL database?
(*) Methodology is pathetic because it overloads words all the time. Mostly to confuse people into buying something. All methodology is crap.
I wonder about all these analogies to engineering. Do engineers make analogies like TheBlueprintIsTheFoo?? -- ???
No, I think you're right, analogies can often lead to inappropriate conclusions and generalizations when extended beyond their initial intent. -- RobertDiFalco
I think TheSourceCodeIsTheSourceCode?. But I'm not selling something. ;) --???
Well, clearly, this is the most correct point of view. I'm just trying to provide a more reasonable compromise to the assertion that TheSourceCodeIsTheDesign. -- RobertDiFalco
I think that if you can assert that TheSourceCodeIsTheSpecification, that you can sometimes also assert that TheSourceCodeIsTheStandard?. This has interesting implications vis a vis "de facto" standards (e.g. Windows) and open source (e.g. Linux). For example, there have been repeated attempts to standardize Unix (see Main Players and Unix Standards: http://www.faqs.org/faqs/unix-faq/faq/part6/section-4.html), none of which were really successful. It's not clear to me what the point would be of standardizing Linux, since everyone has access to the source code.
In TheSourceCodeIsTheDesign, the author really meant that source code is more like design than like implementation, through analogies to other disciplines. He did not mean that all other notions of software designs are invalid, except for the source code. Unfortunately, I see that page misquoted throughout this Wiki as meaning what its title literally says. I suggest the authors move the content to a new page and retire the old one, if they care.
I resonate with the idea that code is specification, especially after trying my hand at some formal specifications. As for terminology, we're screwed as far as I can tell. In this case, what's a specification? I'm sure there are a million opinions on this, many of them having nothing to do with being specific. I think (who cares?) that a specification is a description that is more specific than some other description. In that light, code is a description sufficiently specific (assuming its language is still known) to replicate the system it describes. There are other specifications that are useful but cannot make this claim. For example, I can write an Alcoa specification of the essential state and operations for a system, then run the checker to see if I have described what I thought I meant. In some ways, this kind of specification is more useful than code, since it allows me to catch errors earlier.
Thinking of code as specification is a good cross-cultural mental exercise for coders who faint or vomit at the mention of specifications. If we allow the thought that we've been writing specifications all these years, we might then take a next step and think about how we might write specifications in other ways that might help us get the job done better, faster, etc.
But definitely get rid of those definite articles in the title! -- WaldenMathews
As for terminology, we're screwed as far as I can tell.
Truer words have never been spoken. Or, as WilliamBurroughs would say, language is a virus. -- RobertDiFalco
My attempts to recruit others into the "unscrewing" of the language don't seem to resonate, or resonate very little. See also Richard's comment below. -WM
If they had resonated with others in such a way as to cause any kind of coordinated action you'd probably be accused pretty soon of having started a diabolical conspiracy to undermine Wiki. Believe me, it's better not to cause too much resonance, as dear NormanFoster?, architect of the new MillenniumBridge? in London has just discovered. Of course, he blames the engineers ...
Let me suggest that I do not believe that there is any need to have "design" (or "specification") for software. For years I have heard the comment that software developers do not do design, but software has been written. I also look at other development processes and I do not see them requiring near the amount of paperwork that we have come to believe software development requires. For example, has anyone ever seen a requirements document, a system design document, a test document, or a change request procedure for a software development standard? If it is acceptable for someone to just sit down an write one of those, why should software be any different? Instead of playing word games trying to define "design," why don't we come out and say it is not needed and does not really exist?
"...if they cannot write code, how can they contribute to the design?"
And your point is? :-) Non-programmers contribute to specifications, or indeed, often are the sole source of specifications, which are about what is to be achieved. They cannot contribute to non-specification aspects of design, because design is how to accomplish goals. People who know how, are called "programmers". Nonprogrammers who attempt to contribute to software design just futz up the process -- it happens all the time, but not with good results. Similarly in all technical fields ("Your design document has a problem, here, where it says "router" -- it should say "Cisco router", because I heard they were best.")
Reference: http://www.bleading-edge.com/Publications/C++Journal/Cpjour2.htm
See: TheSourceCodeIsTheDesign, WhatIsSourceCode, TheUnitTestIsTheSpecification, WhatIsaSpecificationAnyway
EditText of this page
(last edited April 18, 2005)
or FindPage with title or text search