function v. method

[Gerhard Fiedler]

On 2006-07-22 16:32:38, danielx wrote:

>>>> ...and source code...
>>>
>>> *shudders* What happened to all the goodness of abstraction?
>>
>> Abstraction as you seem to use it requires complete docs of the interface.
>> Which is what you said you don't have... So the original abstractor broke
>> the abstraction when publishing insufficient docs, not the one who looks
>> into the sources to find out what actually happens.
> 
> Absolutely. I didn't mean the user was breaking abstraction (let's not
> blame the victim). I was saying that we should really have more
> sympathy for him.

I have all the sympathy in the world for him... after all, he's me :)

But one reason why I try to write (and insist on as much as possible from
people writing for or with me) self-documenting code is that wherever you
have documentation and code separated (which is the case of API docs), you
can bet (without losing) that sooner or later code and doc will diverge.
This has a probability that approaches 1 :)

So, I agree with you that good API docs are a good thing, as they tell me
everything I need to know without having to wade through tons of
implementation details that may be interesting but don't serve my immediate
need (of having to use the API). But reality seems to be (and mine so far
definitely is) that these docs, even the good ones, are not completely in
alignment with the reality of the code. (We all know that code has bugs...
and the API always describes, at best, how the code /should/ work. It never
describes how it actually works, including the bugs <g> (this
notwithstanding the bugs that have been elevated to features and henceforth
been described in the API docs).

So... the final authority /is/ the code. I don't see an alternative. For
me, good abstraction doesn't mean I don't have to read the sources; good
abstraction means (among other things) that I can read the sources easily.

Gerhard