>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. -- http://mail.python.org/mailman/listinfo/python-list
