Python style: exceptions vs. sys.exit()

[Steven D'Aprano]

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. There are at 
least four things wrong with the advice to read the source code:


(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.

(3) Source code not always understandable without significant effort. 
Code can be obfuscated, either to hide the algorithm, 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?).

That's why accurate documentation should be preferred in the first place: 
it is easier to read and understand. It might take you hours of hard 
study to learn that function spam(x) raises ValueError if the argument is 
invalid, or two seconds to read it in the docs.

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.

(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. 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... 

How much source code are you expected to read just to understand the four-
line function spam()?


-- 
Steven