Steven D'Aprano a écrit :
On Mon, 29 Sep 2008 18:27:22 +0200, Bruno Desthuilliers wrote:
Lawrence D'Oliveiro a écrit :
In message <[EMAIL PROTECTED]>, Ross Ridge wrote:
You need either use trial and error to find out, or look at the
source.
So what's wrong with using the source as documentation? :)
Don't know... Ok, having higher-level documentation (the big picture,
and quick description of what and how for classes and functions) really
helps. But when it comes to nitty-gritty details, source code is the
best documentation ever, since it's always accurate and up to date.
FWIW, I'm often surprised by people asking questions about some
implementation detail of some open-source library or framework that are
very easily answered just looking at the source code. Reading the source
is 1/ the best way to really know how something is implemented and 2/
usually very instructive.
Reading the source code is good, but it's not a panacea.
Not what I implied.
There are at
least four things wrong with the advice to read the source code:
My "advice to read the source code" was not meant as a *replacement* for
documentation, but as a *complement* to it. What I meant is that you
just can't document each and every detail of implementation.
(1) It's not always available.
(2) Even when the source is available, it is sometimes a legal trap to
read it with respect to patents and copyright. E.g. some Microsoft so-
called "open" licences (but not all) allow you to read the source, but if
you do then everything you program in a related field from that point is
legally contaminated and could be considered a derivative work of
Microsoft's software.
I obviously implied that source was freely available and you had the
right to read it. Else it just makes no sense.
(3) Source code not always understandable without significant effort.
That's why reading the source can have a great educational value, isn't
it ?-)
Code can be obfuscated, either to hide the algorithm,
same problem as closed-source software - not concerned by this advice.
as an optimization,
or simply because the coder is cleverer than you are. It might be in a
language you don't understand (e.g. Python built-ins are written in C,
not Python. I have to learn C to find out what exceptions sorted() can
raise?).
Every developer should have at least basic knowledge of C. MHO of course.
That's why accurate documentation should be preferred in the first place.
Indeed. Did I say otherwise ? Now not all code has accurate
documentation, and then you're happy to be able to access and possibly
understand the source code. I'm not talking about an ideal world here.
(snip)
Yes, documentation can fall behind the source code, but once the code is
stable and the documentation has caught up and is accurate, there's no
reason to re-invent the wheel by slugging through the source just to find
out something already documented.
Once again, that's not what I said.
(4) Even when the source code is available, legally unencumbered, in a
language you understand and not too complicated for you to grasp, there's
the combinatorial explosion: you may need to read and understand an
arbitrarily large and complex chain of software merely to know what a
single function can do.
Yes, this happens when hi-level documentation is lacking. At least you
have a chance to gain some insight !-)
E.g. you want to know what exceptions function
spam() can raise:
def spam(x):
a = 1
b = 2
c = ham(x)
return fried_eggs(a, b, c)
Now you need to understand ham() and fried_eggs(), but they aren't
documented either. So you turn to their source code, and each of them
call two functions, each of which call another two functions, each of
which call *another* two functions...
And still you're a lucky guy if there's no callback, conditional import
and / or polymorphic dispatch involved.
Steve, I may not have been clear, but I didn't meant that code shouldn't
be documented. I was :
1/ answering to the question "So what's wrong with using the source as
documentation?", my own personal answer being that it's something I
often do, whether because I want to find out some detail not covered by
the available documentation, whatever this available documention is worth
2/ digressing about the fact that, to my suprise, few developpers seem
to *first* have a look at the source code when either documentation is
lacking or they'd like to know more about some implementation detail.
But FWIW, it seems that few developpers even bother reading the
documentation at all :(
--
http://mail.python.org/mailman/listinfo/python-list
