David Naseby
11/20/2003 6:02:00 AM
>-----Original Message-----
>From: Simon Kitching [mailto:simon@ecnetwork.co.nz]
>> What do you think you need to protect them /from/, exactly?
>
>No, it's more to protect me!
>
>It's to protect me from questions like:
>
>"Hey, what kind of object is this method expecting? It isn't documented
>anywhere and I can't understand the source code".
If the developer of the library was crap enough to leave the library
completely undocumented, what makes you think she will put in (optional)
type clauses?
>
>"Hey, I'm getting this message from the XXX library about do_foo not
>existing on parameter bar. I must be doing something wrong.
>How do I fix
>it?"
"Hey, I'm getting this message from the XXX library about parameter bar not
implementing the interface FooDoer. How do I fix it?" I really don't see
what's unclear about the exact error message, and why a more obfuscated
"interface" makes it clearer. This question is followed up with "What does
the FooDoer interface have to implement?". If the library developer was that
crap with documentation, why is the interface going to be more documented
than an exact message failure is self-documenting???
>"Hey, I'm supposed to fix this library method. What parameters are
>people allowed to pass to it?"
"Hey, this library method expects a
SomeLibrary::Interfaces::IFooUndocumented interface passed to it. What
parameters does IFooUndocumented expect?". An undocumented library is crap.
A documented library is good. This whole thread is trying and IMO failing to
suggest that type-checking, or type-verification, or something, will somehow
replace or compliment bad documentation.
>and the corollary question:
>
>"Hey, your team isn't making much progress on this project,
>despite this
>Ruby language you suggested. Why shouldn't I fire you?"
>
Can't answer this one at all :)
David.