thesourcecodeisthedesign.html

极限编程 Extream Programing

is some significant "design" work in how the system executable(s)
and/or libraries are built (constructed, generated, and derived) from
the source code. But you likely won't see much of that indicated in
the source code of the program itself. Some folks would call this the
physical (rather than logical) architecture of the system. It is also
sometimes called "code architecture" (Does that mean the directory tree
<em>is</em> the code architecture?)
<p>
In the case of compiling and linking the source code via a program
like make(1), I think you can argue that the Makefile (and any
associated scripts) are the source code, and so the Makefiles are the
(build) design (or at least they should be ;-). Would others agree
with that?
<p>
The problem is, I find I need to use more comments in my
Makefiles. The make(1) language/syntax seems a bit less self-documenting
or self-evident than say, Smalltalk, or Lisp, or C++ or C. I would
probably rank it somewhere between C and Assembly. OTOH - Eiffel has
something called LACE which is closer to being at the same level as
Eiffel. <a href="http://c2.com/cgi/wiki?VisualWorks">VisualWorks</a> has packages and parcels, which are still somewhat
low-level, but I think they can just (barely) manage to be self
documenting. Smalltalk/Envy on the other hand is much nicer.
<p>
-- Brad Appleton
<p>
<UL>
<li> I don't see what the &quot;level&quot; of Makefiles has to do with it. You check your Makefiles into RCS, right?  And you wouldn't dare distribute the source code without its Makefile (that reminds me, I need to put a pointer to <a href="http://c2.com/cgi/wiki?RecursiveMakeConsideredHarmful">RecursiveMakeConsideredHarmful</a>). When I do <a href="LiterateProgramming.html">LiterateProgramming</a> using NoWeb<a href="http://c2.com/cgi/wiki?edit=NoWeb">?</a>, the Makefile is part of the literate program -- which, I admit, can make bootstrapping a bit challenging....  --<a href="http://c2.com/cgi/wiki?BillTrost">BillTrost</a>
<p>
<li> I wasn't referring to the &quot;level&quot; of Makefiles, but of the make syntax itself. I believe it is not nearly as self-explanatory as C++ or Java or Smalltalk or Perl or Lisp. It looks a bit closer to assembly IMHO (especially when you use &quot;targets&quot; to factor out common things, almost like a subroutine). So I think it would require more comments than Ron or Michael would recommend using in corresponding Smalltalk or C++ code because of this. It seems to me that most of the &quot;code is the design&quot; discussion is referring to fairly minimal use of comments. I think one reason we can even talk about having the code be the design in this manner, is that we all seem to be implying high-level languages for our programming. Would we be as adamant about this if we were talking about raw assembly or machine code? I suspect that we could still make the same argument for assembly, but we would probably demand more in the way of comments. Am I incorrect in thinking this? -- <a href="http://c2.com/cgi/wiki?BradAppleton">BradAppleton</a>
<p>
<li> I think you are correct.  I'm a chip designer, working with HDL instead of schematics.  Which makes me a programmer I guess. However, the tools and &quot;languages&quot; I need to use are so heterogenous, incompatible in terms of data interchange, and less than robust that they may as well be low-level languages.  As a result, I spend a huge amount of time writing Makefiles, and Perl widgets in order to hold it all together.  In a recent chip with around 50,000 lines of what would normally be recognised as &quot;source&quot;, we had to construct over 10,000 lines of &quot;Bolt It Together Stuff&quot;.  Those &quot;BITS&quot; all had to be designed and configuration managed as lovingly as the chip proper.  To me, it's all source. (<a href="mailto:[e-mail]">mailto:[e-mail]</a>)
<p>
<li> Perhaps Makefiles &amp; directory structures correspond to manufacturing instructions in hardware engineering: they're just as necessary, and related to but separate from the design of the artifact itself.  There's a special set of skills to do them well, and so larger organizations might hand them over to specialists.  At the same time, designs which can't be easily manufactured are bad, like programs that are slow or hard to link because of massive dependencies, etc.  Just an idea: I like the analogy a lot. -- <a href="http://c2.com/cgi/wiki?MartinPool">MartinPool</a>
</UL>
<hr>
Something's been nagging at me about this page for along time. I don't believe that the article says <em>The</em> source code is
<em>the</em> design, as the XPers would have us gloss it. What the article seems to me to be saying is: the kind of document that a source code document is, is &quot;design&quot;.
<p>
That, yes, but more. The source code is also the ONLY document in whatever collection you may have that is guaranteed to reflect reality exactly. As such, it is the only design document that is known to be true. The thoughts, dreams, and fantasies of the designer are only real insofar as they are in the code. The pictures in the reams of UML are only veridical insofar as they are in the code. The source code is the design in a way that no other document can claim.  One other thought: maybe gloss isn't in the writing, maybe it's in the reading. --<a href="RonJeffries.html">RonJeffries</a>
<hr>
<a href="TheSourceCodeIsTheDesign.html">TheSourceCodeIsTheDesign</a> may be one of the oldest ideas in software development.
<p>
Flashback... 1968/69 trying to work out how to hack a compiler to add
a new device...  tried drawing a flowchart of a core dump... 20 doublesided
pages...  experienced guy walks in.... &quot;Why don't you ask the company
for the documentation?&quot;  So I phone up the vendor and they send me...
20 pages of code written in the language that they were compiling...
Can't say it helped me very much.  A very good compiler however.
<p>
Questions: Can our current forms of source code be improved?
<p>
<em>Of course.  And the quest to do so motivates much of the history of programming language design.  My take on the article mentioned here is that it has always been fundamentally true, but the low levels of abstraction in programming languages make the source code a poor design document.  As languages improve, our code can be closer to a direct expression of the design.  More &quot;essence&quot; and less &quot;accident&quot;, to use <a href="http://c2.com/cgi/wiki?FredBrooks">FredBrooks</a>' terms.  --<a href="http://c2.com/cgi/wiki?GlennVanderburg">GlennVanderburg</a></em>
<p>
-- <a href="http://c2.com/cgi/wiki?DickBotting">DickBotting</a>
<p>
<em>One of the primary goals of the</em> <a href="http://c2.com/cgi/wiki?EiffelLanguage">EiffelLanguage</a> <em>is to capture both the design and the implementation together in one place, using a simple and clear notation. Alas, the Eiffel notation is so simple and clear that it's considered a fool's language by those whose careers depend on hacking out code in complex and arcane programming languages. Eiffel can only be appreciated by designers. Unfortunately, designers have been convinced that graphical representations (UML) are the only true way to express a design, and although the 'L' in UML stands for 'language', it is not a language which a machine can readily process to extract the essence and the elements of the design.</em>
<p>
<hr>
<p>
<em>A long time ago I thought I had to have a good design to write good code.  So I tried to get my design perfect, before I wrote any code.  My design was always imperfect and that reflected in my code.  Now I just try to write good code, and find that it has good design.</em>
<p>
<hr>
<p>
After reading Jack Reeves' article, I believe he is essentially correct.  It reminds me of a quote from the book, <em>Structure and Interpretation of Computer Programs</em> by Abelson and Sussman, &quot;Programs must be written for people to read, and only incidentally for machines to execute.&quot;
<p>
To avoid the problems of CASE tools where the generated code is often incomplete and the developer-corrected code is incompatible with the tool, perhaps what we need to do is to place the descriptive drawings (e.g., UML) directly in the compilable code artifacts.
<p>
--<a href="http://c2.com/cgi/wiki?JimTulley">JimTulley</a>
<p>
<em>Or vice versa, perhaps in the style of the TogetherTools<a href="http://c2.com/cgi/wiki?edit=TogetherTools">?</a>. One problem here is that too much of the UML is C++ with lines drawn around it.</em>
<p>
I believe (and practice) that the correct approach is to consider the
code generator to be part of your source code. The design is the
combination of the diagrams plus their translator(s) plus any other
source code generators plus any other source code. Each fact should
be expressed within the design <a href="http://c2.com/cgi/wiki?OnceAndOnlyOnce">OnceAndOnlyOnce</a>, but the form of that
fact could be as a diagram, as text (table), as translator code or
as traditional source code (of course, this approach is applied
recursively to the translator programs -- hence the <a href="http://c2.com/cgi/wiki?ShlaerMellorMethod">ShlaerMellorMethod</a>
uses the term <a href="http://c2.com/cgi/wiki?RecursiveDesign">RecursiveDesign</a> for this approach). See also, <a href="http://c2.com/cgi/wiki?MetaRefactoring">MetaRefactoring</a>. -- <a href="http://c2.com/cgi/wiki?DaveWhipp">DaveWhipp</a>
<p>
<hr>
<p>
Hmm, So what if someone besides a programmer who understands the language the code is written in wants to review the design? -- <a href="http://c2.com/cgi/wiki?StevenNewton">StevenNewton</a>
<p>
<em>Tough. If this exercise will generate profit, then it can pay for a translator to render the code into the format the reviewer understands. Otherwise, we shan't screw with our entire methodology to add a &quot;documentation layer&quot; on the outside chance that we might someday need to satisfy an unqualified reviewer's curiosity. --PCP</em>
<p>
<hr>
<p>
<strong>The car is the design.</strong>
<p>
My car broke down and i wanted to fix it. I also had some other mods in mind.
When i called up the manufacturer for one of them books describing the car
in great detail so nearly any idiot can fix the car they laughed and said
you have the car, what else do you need? It's obvious. Just a take a look
at the car, it's clearly self documenting. Looking at the car didn't
help me much. 10 days later I asked if i could talk to anyone
who might know how the car works so i could ask some questions. They said
old ned was on vacation and older ned died. Young ned just started, but
he only understands the spark plugs. Besides, the car is the design. That's
all you need. --???
<p>
<em>Ages ago, in a university setting when there was &quot;the computer&quot;, one of the &quot;leaders&quot; would always tell people when they came to him for help on a program they were hacking, &quot;Read the code!&quot; I thought this was cruel when you had people who were just starting out confronted with thousands of lines of wizardly code they were trying to do something with. Perhaps we should say TheSourceCodeIsTheDetailedBlueprint<a href="http://c2.com/cgi/wiki?edit=TheSourceCodeIsTheDetailedBlueprint">?</a>. I know there our times I feel the need of even the simplest top-level overview of a system. -- <a href="http://c2.com/cgi/wiki?RobertField">RobertField</a></em>
<p>
Bad analogy.  The car is clearly the binary.  The source code is the design for the car. --<a href="http://c2.com/cgi/wiki?JohnBrewer">JohnBrewer</a>
<p>
I disagree. If the car is the binary we would maintain systems by tweaking their byte-code. Changing the <em>car design</em> makes no concommitant change to the <em>actual car</em>.  You can't fix a car by fixing its design. However, you <em>can</em> fix a system by fixing its source code. The car is clearly <strong>not</strong> the binary as we don't normally <em>tinker</em> with binary after it is compiled. We tinker with the source code. It's nice and pretty to think of compiling and linking as manufacturing but its just an analogy no truer than any other analogies to hard-engineering. --<a href="http://c2.com/cgi/wiki?RobertDiFalco">RobertDiFalco</a>
<p>
<em>You would tinker with the byte code if it cost you $20,000 to compile.</em> --<a href="http://c2.com/cgi/wiki?KevinLewis">KevinLewis</a>
<p>
<em>I used to spend an inordinate amount of time tinkering directly with machine code, while it was running no-less.  Aye, we 'ad it tough! ;-) --<a href="http://c2.com/cgi/wiki?TomAyerst">TomAyerst</a></em>
<p>
Seems to me it's a very good analogy. if Car == Source Code &amp;&amp; Source Code == Design then changing the Car should change the Design.  Whoops!  Guess one of these equivalencies doesn't hold. -- <a href="http://c2.com/cgi/wiki?StevenNewton">StevenNewton</a>
<p>
Well, this is my point. The source code isn't the design. It never was. However, I may be convinced to believe that <a href="http://c2.com/cgi/wiki?TheSourceCodeIsTheSpecification">TheSourceCodeIsTheSpecification</a> but even this cannot be supported by syllogisms and equivalencies. However, it's a little closer to the truth than <a href="TheSourceCodeIsTheDesign.html">TheSourceCodeIsTheDesign</a>, don't you think? --<a href="http://c2.com/cgi/wiki?RobertDiFalco">RobertDiFalco</a>
<p>
<em>If the car is the binary we would maintain systems by tweaking their byte-code.</em> 
<p>
This is precisely how we do it.  It's just called &quot;doing a clean install&quot;.  People without compilers typically replace binary components, just as people without car factories typically replace broken parts.  -<a href="http://c2.com/cgi/wiki?JohnBrewer">JohnBrewer</a>
<p>