The Source Code Is The Specification

TheUnitTestIsTheSpecification and TheUserGuideIsTheSpecification?.

 for(1..3){
    print "Specification != DetailedDesign\n";
 }

Now go see TheSourceCodeIsTheDetailedDesign.

---

Moved from TheSourceCodeIsTheDesign

Wow! That was great. Clearly, the SourceCode is only one view of the design. This is another XP simplification that can often lead people to trouble. You may also want to tell drivers going over the Willamette that the Bridge they are riding on was constructed with none of that evil DesignUpFront. And, whenever it is in need of repair, even by experts, that they need no engineering schemata because the girders, welds, and rivets are the design. I'm tending to think all of these analogies (mine included) lead to frightening conclusions if extended. -- RobertDiFalco

I want to amend my comments and say that I believe TheSourceCodeIsTheDesign is a bit of a fallacy and that TheSourceCodeIsTheSpecification is probably a little closer to the truth. It used to be that engineers would create designs, specifications, and then implementation. I believe, especially with the languages of today that specification is no longer necessary because TheSourceCodeIsTheSpecification. However, I do not believe that TheSourceCodeIsTheDesign - but I do think it is a nice ethic. However, it could be that as languages improve and become more high-level that we will be able to attain TheSourceCodeIsTheDesign. It's just not true of our existing languages. -- RobertDiFalco

Robert, have you read the article that is mentioned at the start of this page? The primary thesis of the article is that, compared to physical engineering and manufacturing, software is fundamentally different. In software, we're blessed with an extraordinarily cheap manufacturing process (type "make"). So of course we go back and change the design; it's a lot more accessible and amenable to change than the artifact, and going from the design to the artifact is trivial. Not so with a car, so the owner has to fix the artifact. In your example, following the mapping described in the JackReeves article, the car is clearly analogous to the binary.

I'm not actually disagreeing with you about the "design vs. specification" point (although I think the distinction is minor). I just wanted to point out that your argument completely misses the point of the original article, which is well worth reading. -- GlennVanderburg

While I haven't read the article for probably five or six years, my point was more about TheSourceCodeIsTheDesign ethic in the large (or at least how it is bandied about on Wiki as a justification for no upfront design). My comments had very little to do with the article. The article is often used to support TheSourceCodeIsTheDesign but I don't believe the whole concept is predicated on the Reeves article. Maybe I'm wrong. However, I don't think you can say I miss the point just because I disagree. FWIW, I'll print it out right now and give it another read but I doubt I'll be more inclined to agree now than I did then. -- RobertDiFalco

Sorry, I didn't mean you'd missed the point. I was just being narrow and pedantic (one of my email addresses is glv@pedant.com, for good reason). I just don't think your argument about the car supports your view, because that argument misses the point. (And, to me at least, the concept is predicated on the Reeves article. I held essentially your position until I read that article, which made a believer out of me.) -- glv

Wow, we should have passed in the night. I just moved the other direction a couple of years ago. However, TheSourceCodeIsTheDesign is still close to my heart, I've just seen it break-down too often in complex projects. I've come to think of traditional design documentation as being relevant only when it describes the problem domain and the resulting system at a high-level of abstraction (i.e. roles versus classes). I then view the specification as a detailed view of how the system design is implemented. I suppose this is why, if one must make analogies, that I feel TheSourceCodeIsTheSpecification is more accurate. To me, it didn't even seem like Reeves himself was completely satisfied with either analogy. The truth is probably this...that neither are correct. Programming is probably more like algebra than engineering, but that doesn't even fit completely. -- RobertDiFalco

Well, this goes to what I meant when I said that I thought your distinction was mostly semantics. I view the source code (and what you've called the specifications) as the detailed design, which might be sufficient for small projects. But for larger, more complex designs, you might need design overview documents to introduce you to the design and help you know where to start. I don't think many people (even those who believe TheSourceCodeIsTheDesign) would argue with that, and I suspect that the design of a 747 has some high-level overview documents about the design, even though what really matters is the detailed design. So when you say TheSourceCodeIsTheSpecification, it seems to mean the same thing as "the source code is the detailed design", which is what I believe. -- glv

Seems like, besides semantics we agree. Rather than bat around terms that may be ambiguous like design versus detailed design I find it clearer to say design versus specification. However, if we agree on the concepts, that's pretty encouraging and its probably just a waste of time to debate the terms. -- RobertDiFalco