>>> The fact that scientific journal articles start with a documentation >>> string >>> called an abstract does not indicate that scientific English fails as a >>> human communication medium. Function docstrings say what the function >>> does >>> and how to use it without reading the code. They can be pulled out and >>> displayed elsewhere. They also guide the reading of the code. Abstracts >>> serve the same functions. >> >> >> A paper, with topic introduction, methods exposition, data/results >> description and discussion is a poor analog to a function. I would >> compare the abstract of a scientific paper to the overview section of >> a program's documentation. The great majority of the docstrings I see >> are basically signature rehashes with added type information and >> assertions, followed by a single sentence English gloss-over. If the >> code were sufficiently intuitive and expressive, that would be >> redundant. Of course, there will always be morbidly obese functions >> and coders that like to wax philosophical or give history lessons in >> comments. > > > Both abstracts and doc strings are designed to be and are read independently > of the stuff they summarize. Perhaps you do not use help(obj) as often as > some other people do.
I find help() to be mostly useless because of the clutter induced by double under methods. I use IPython, and I typically will either use tab name completion with the "?" feature or %edit <obj> if I really need to dig around. I teach Python to groups from time to time as part of my job, and I usually only mention help() as something of an afterthought, since typically people react to the output like a deer in headlights. Some sort of semantic function and class search from the interpreter would probably win a lot of fans, but I don't know that it is possible without a standard annotation format and the addition of a namespace cache to pyc files. -- http://mail.python.org/mailman/listinfo/python-list
