From: Dan Doel <djd15@...>
Date: 2003-11-22T06:50:39+09:00
Subject: Re: "stereotyping"

Sean O'Dell wrote:

>>But again, its less hassle to document your API than to do rigourous
>>argument checking.
>>    
>>
>
>No, it's more hassle.  To update a document, you have to open a different 
>file, and if you make a typo or just plain write it wrong, there is nothing 
>to stop you from doing so.  Interfaces can be described in the same source 
>file as your class definition, so it's easy to find and update, plus, you 
>can't update it wrong, or your code gives you errors.
>  
>
You always have to update documentation when you change something.  
Having an interface checking
system doesn't mean that you don't have to document your code.  So in 
effect, having interfaces means
you have to update two different places when you make an interface 
change (three, actually, if you
count the code that uses the interface), and there's more things that 
can get out of sync.

Besides, with systems like RDoc you can make all documentation 
annotations in your source and
generate the documentation from there, so it's really no more or less 
convenient than having an
interface definition in your source, at least for documentation purposes.

- Dan