Steven D'Aprano <steve+comp.lang.pyt...@pearwood.info> wrote: > Given the practical reality that documentation is often neglected, there > is a school of thought that says that *code* is the One True source of > information about what the code does, that documentation is at best a > hint or at worst completely redundant.
Yes, there is such a school. Those people are full of bovine excrement. > If function f() puts the cat on the mat, but is documented as putting > the hat on the cat, how do you know whether the documentation is > wrong or the code? Documentation should describe intent and interface. Yes, the code says what the code does. But, the interface description says what it's supposed to do. Can the docs be wrong? Of course they can. Usually because somebody changed the code and didn't bother to change the docs. My take on people who never document anything is that they're just plain lazy. Go ahead, ask me how I really feel about the topic :-) -- http://mail.python.org/mailman/listinfo/python-list
