function v. method

[Bruno Desthuilliers]

danielx a écrit :
> Bruno Desthuilliers wrote:
> 
>>danielx a écrit :
>>
>>>Bruno Desthuilliers wrote:
>>>
>>>
>>>>danielx wrote:
>>>>
>>>>
>>>>>Bruno Desthuilliers wrote:
>>>>>
>>>>>
>>>>>
>>>>>>danielx wrote:
>>>>>>
>>>>
>>>>(snip)
>>>>
>>>>
>>>>>>>Obviously, such things would be omitted from your docs, but users also
>>>>>>>learn by interacting with Python, which is really one of Python's great
>>>>>>>virtues. When supporting documents aren't sufficient to learn an api
>>>>>>>(I'm sure this never happens, so just humor me), you can always turn to
>>>>>>>interactive Python.
>>>>>>
>>>>>>...and source code...
>>>>>
>>>>>
>>>>>*shudders* What happened to all the goodness of abstraction?
>>>>
>>>>Compared to machine language, Python source code is really abstration.
>>>>
>>>
>>>And machine language is an abstraction of pushing electrons around
>>>circuits. I'm not sure I see your point, unless it is simply that
>>>Python is easier than asm.
>>
>>Python is very hi-level, and very often well-written Python code is it's
>>own better documentation.
> 
> 
> Yes, Python is very easy to read, but who's supposed to be reading it?
> Maintainers or users?

In an ideal world, nobody !-)

> I'm really against code acting as its own
> documentation. 

I'm really for it, because :

> Of course the code is authoritative,

indeed.

> but should we
> really EXPECT it to serve as a reference to users??

Unless you're able to maintain a good, accurate and always up to date 
documentation, you can be sure users (ie other programmers) will turn to 
the code. Also, there are cases where even a pretty good doc is not 
enough, and you really have to turn to the code to know for sure how to 
best implement something.

FWIW, reading source code can be very instructive...