From: Ryan Leavengood <mrcode@...>
Date: 2005-04-28T09:21:17+09:00
Subject: Re: Comments Are More Important Than Code

Jim Freeze wrote:
>>* Dave Fayram <dfayram@gmail.com> [2005-04-28 08:19:29 +0900]:
>>
>>>Neither piece of code is lying. Code cannot lie. The unit test says,
>----------------------------------^^^^^^^^^^^^^^^
>
> If you will permit me to philosophize for a minute here.

I was not wanting to jump into this thread, but I found Jim's message
interesting so I will. In a sense you are deflating Dave's argument about
the pureness of code by using the ambiguity of language, particularly the
English language. So in a sense you are showing the weakness of
documentation heavy development. There is so much room for ambiguity in
language, yet in a huge percentage of cases, code will do what it says it
will. Your "code is lying" examples are so out of the ordinary to be
considered statistically impossible.

Whereas misinterpretation of documentation is extremely common, especially
considering the effort required to write good documentation and keep it
up-to-date. In fact I would say the dangers of having bad, out-of-date
documentation are large enough to warrant keeping the documentation as
simple and small as possible. Plus verbosity is just irritating.

To conclude with an example (which is basically a Straw Man, so don't try
to call me on it since I admit it):

If you run this in the Ruby interpreter you have a pretty good idea of
what it will do:

puts "Hey look at me!"

But how about this English:

The following sentence is a lie. The previous sentence is absolutely true.

I'm sure others can come up with much better paradoxical or ambiguous
English phrases.

Ryan Leavengood