Re: doc patch: weakref.

Hugh Sasse wrote:
> On Thu, 3 Aug 2006, mathew wrote:
>   
>> I've explained before that unit tests are not a *specification* of anything.
>> They may *test* a specification, but in general it is not possible to convert
>> a specification into a set of unit tests without losing information.
>>     
>
> They express intent in a machine-useable way.

Yes, but it's not the machine that cares what the API is. APIs are for 
humans.

>   They may be incomplete, but the advantage they have over docs is that in TDD they get fixed.
>   

And the disadvantages they have when used as an excuse for not bothering 
with documentation, include:

- Code becomes unrefactorable

- Potential new Ruby programmers are discouraged

- Productivity is reduced

I think those are worse than having documentation occasionally not 
keeping step with code changes.

>> For example, for any finite set of unit tests that attempt to specify the
>> behavior of +, I can define a function f() that passes all those tests, but
>> behaves differently to +, and code that relies on the f() behavior.
>>     
>
> Yes.  But for any finite amount of documentation, you can find someone
> who will misunderstand it.  Hence the original Murphy's law.  In agile
> thinking code beats docs.  [I'm not trying to reduce software construction
> to "rock, paper, scissors", just to say that what can be automated
> should be.]
>   

Show me a serious agile software developer who advocates not having API 
documentation?

> I found the Wikipedia page about denotational
> semantics to be less than light reading :-)

You should try actually *using* denotational semantics :-)


mathew