Python style: exceptions vs. sys.exit()

[Bruno Desthuilliers]

Steven D'Aprano a écrit :
> On Mon, 29 Sep 2008 18:27:22 +0200, Bruno Desthuilliers wrote:
> 
>> Lawrence D'Oliveiro a écrit :
>>> In message <gbgu3v$mie$1 at rumours.uwaterloo.ca>, 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 :(