How to except the unexpected?

[plahey at alumni.caltech.edu]

>Yes, and that's the Right Thing(tm) to do. Source code don't lie. Source
>  code don't get out of sync. So source code *is* the best documentation
>(or at least the most accurate).

I could not disagree more strongly with this.  Not just no, but hell
no!

>Yes, and that's the Right Thing(tm) to do.

No, it is a horrible thing to do.  But since the documentation of some
modules is just plain horrible we sometimes have no choice.

> Source code don't lie.  Source code don't get out of sync.

True but implementation details change from release to release.

> So source code *is* the best documentation (or at least the most accurate).

No, source code is the *worst possible* documentation because it makes
no distinction between implementation detail and method contract.  If
the implementer considers the implementation to be the documentation
then his/her refactoring options are significantly reduced.  Typically
implementers are not aware of this and they refactor anyway, breaking
client code left and right.

The C++ FAQ has a nice discussion of this issue.  Minimally acceptable
documentation consists of the following (I think this is language
independent):

PURPOSE: What does this method/function do
REQUIRE: pre-conditions - What must have happened before calling this
method (or restrictions on the domain of the inputs)
PROMISE: post-conditions - What can you expect upon return or what
exceptions can be thrown

I consider the above to be the minimal amount of documentation that is
acceptable.  If you have less than that, I consider the method to be
undocumented.  Needless to say, I consider lots of code that I see to
be undocumented.

If you don't have the above, you get the problems that OP was hitting
(or worse, see the C++ FAQ).  I am not a huge fan of Java's ubiquitous
use of checked exceptions or even of static typing but it does help
supply some of the above documentation (although in a suboptimal way)
that must be supplied by hand in Python.  This is the dirty little
secret of dynamically typed languages.  It makes proper documentation
even more important because method signatures supply less information.