Re: Identifying exceptions that can be raised

From: Roy Smith (roy_at_panix.com)
Date: 11/22/04 

Date: Mon, 22 Nov 2004 08:46:39 -0500

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

Peter Hansen <peter@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.

Relevant Pages

  • Re: GoTo in Java
    ... I'm saying that is a hypothetical which, so far, I have not encountered ... methods of user interface and documentation, ... It would be wise to trap overflow and ensure ... ADD INCREMENT TO COUNT ON OVERFLOW CALL COUNT-ERROR-HANDLER ...
    (comp.lang.cobol)
  • Re: Fraction
    ... in the documentation whose title is "division". ... in front of this 3rd paragraph, you would generate an index entry ... which many times is just a politer way of saying "if you want it, go do it yourself, who is stopping you?". ... The things that go without saying needn't be like that if the author of a code actually thinks about it while writing the documentation -- but for this a programmer needs to realize this himself. ...
    (comp.graphics.apps.gnuplot)
  • Re: Where is the notificiation about IE zero day vulnerablity?
    ... You are refusing to do research and are ... Saying 'it's there, find it' is easy. ... A man who loves/believes/is passionate about what they speak of is willing ... and able to present documentation at a moments notice - backing up what they ...
    (microsoft.public.security)
  • Re: Measuring time differences
    ... > use in Microsoft Windows than Microsoft do you are giving BAD advice. ... used to compare times. ... The MS documentation simply says you shouldn't ... I'm not saying its not there, ...
    (comp.lang.c)
  • Re: Can anyone tell me
    ... should be used even if it is less efficent because it is self documenting. ... I'm not saying documentation is required. ... ByRef, you should just know that changing the value in the called procedure ...
    (microsoft.public.vb.general.discussion)
Loading