Identifying exceptions that can be raised

[Roy Smith]

I wrote:
>> You're saying you should write the code without even looking at 
>> the documentation.

Peter Hansen <peter at engcorp.com> wrote:
> Did I say that somewhere?

You said, "Perhaps it's actually documented... I don't know and didn't 
bother looking."  If I misinterpreted your statement, I apologize.

> In other words, the documentation in this case happens to align
> with the actual behaviour of file objects.
> 
> Now I ask you, how often does documentation either not mention
> the fact at all (which was the topic of this thread until now),
> or -- perhaps less common with standard library code, but widespread
> with other code -- mention things that are inaccurate and wrong?

Of course there is bad documentation in the world.  If the documented 
and actual behavior of the code differ, there's clearly a bug somewhere.  
It could be that the documentation is wrong, or it could be that the 
code is wrong.  Both happen.  Both kinds of bugs should be fixed when 
they are discovered.

> In other words, which should one trust more, the documentation
> or the actual observed behaviour?

Well, that's an interesting question, and I'm not sure there's a simple 
answer to it.  Certainly, if my testing determines that read() throws 
ValueError under certain situations which are not documented, it would 
be foolish for me to pretend that it didn't happen because the 
documentation doesn't say so.  But on the other hand, if I discovered 
that math.pi had the value 3, I would be equally foolish to write code 
which depended on that behavior.

> Ultimately, however, this is a silly argument, because neither
> you nor I write code solely in the manner I described, nor
> in the manner you appear to be recommending (i.e. going exclusively
> based on the documentation), so I'm not even sure why you
> wrote...

I never recommended going exclusively from the docs.  I started out by 
saying:

> I'm a big fan of test-driven development, but not to the extent that I 
> feel I can ignore reading the documentation to see how something is 
> supposed to work.

Anyway, it would look like both of us have unintentionally 
misinterpreted what each other has said.  I think in the end we both 
agree that reading the docs is important, and testing is important too.  
Both give us information which is unavailable from the other.