From: Dave Fayram <dfayram@...>
Date: 2005-04-28T07:09:30+09:00
Subject: Re: Comments Are More Important Than Code

James Britt said:
> Positing that documentation exists to document code,
> and that code does not exist to follow documentation,
> is begging the question.

I am sitting on a bench at a train station next to you. We are both
waiting for a train to show up. I'm explaining to you how these
"modern" trains work, and it's all you can do to not to fall alseep as
I explain it in complete, mindless detail. Then suddenly I stand bolt
upright. Off in the distance, you can see the train.

"Holy smokes, the backwash distillerifier has an inversion field
surrounding its nebulae!" I exclaim, pointing vigorously. "That train
is going to blow up." The train shows up, stops, picks us all up, and
goes about its merry way. I still continue to ramble, "This makes no
sense. With that inversion field eating its camera obscura, the
vivacity of the engine should make it a portal to the plane of fire..."
and so on.

Who is wrong? Me, because my explanation was wrong, or the train,
because it didn't behave the way I explained it would? The train meets
its requirements. It got us from point A to point B. But for some
reason my expert knowledge of trains has been invalidated (probably by
windmills and sky-punching, but let's not go there).

Documentation can lie. Code cannot lie. Therefore, the code is
authorative. :)