On Friday 21 November 2003 01:50 pm, Dan Doel wrote:
> 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.

Not always.  If you provide code to others and are responsible enough to do 
so, sure.  On team projects, documentation happens very sporadically.  RAA is 
full of non or poorly documentation code.  It is a good habit to have, but 
humans often don't keep up with as well as they should.

> 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.

Or, you could argue, the interface description could serve as the source for 
your API documentation.  I'm going to add that to the wiki; the idea just 
occurred to me.  Automatic documentation generation would be extremely easy 
if you had interface objects to query.

> 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.

That much is a plus, but the biggest problem I have with that is the same as 
the problem I had with defining interfaces through classes: methods are 
spread out by the code inside them.  Browsing a class is not all that 
pleasant because of that.  Smaller source files aren't so bad, but when a lot 
of code sits in a source file, everything gets really spread out.

	Sean O'Dell