Which means, it is the most efficient way to maintain code. All kinds of documentation is right within the code. There are tools to get the documentation into different formats. Javadoc can do the same thing? Sorry folks, no. Look at how Python is an engineer friendly language, by actually supporting a __doc__ attribute for every module, class and function. This is much better than fooling around with slash-star-star ... star-slash.There's more in the post, going into the joys of the new (Python 2.2 or later)
A little too simplistic definition (07 Jul 2003)
help(obj) function built into the Python interpreter which basically generates something like a man page based on the data in the object passed in (which may be an object instance, a class, a module, etc) (dir, help, and pprint).
Ah, pprint. This is a terrific Python module that "pretty prints" Python data structures. It comes in very handy when looking at large tuples (especially nested tuples), lists, and dictionaries. A module function that I've been using lately is pformat(object) along with Zope's zLOG logging module to log what data is being sent to LDAP as part of the project I'm currently working on:
modlist = mod_entry_generator(old, rec, nodelete, mod_only)
if __debug__:
## Avoided when Python is run with -O option
zLOG.LOG("LDAP.Gateway", zLOG.BLATHER, "Modifying DN: %s" % dn,
"%s\n" % pprint.pformat(modlist))
c.modify_s(dn, modlist)
The modlist is a tuple of tuples in the form of (OP, ATTR, VALUE). Since the modlist can grow quite long, or the VALUE items themselves can be quite long lists (for multi-value attributes), I get a (relatively) readable log entry:
((2, 'mail', ['bjones@example.com']),
(2,
'mailAlternateAddress',
['barnabyjones@example.com',
'bjones@example.net',
'barnabyjones@example.net']))
There are a couple of small notes about the above code. First is the use of the if __debug__: statement. When Python is run with the -O or -OO flags, __debug__ is set to false. It's advisable that when deploying Python programs that -O is set. This also removes assert statements from the compiled bytecodes. -OO does the regular optimizations and removes docstrings from the bytecodes as well.
Second is the use of zLOG.BLATHER. BLATHER is a -100 value in the zLOG level system. By default, anything less than zLOG.INFO (0) is not written to the logs. Using zLOG.BLATHER, zLOG.DEBUG (-200), and zLOG.TRACE (-300) are advisable ways of monitoring Zope operations and data during development time that can be disabled at deployment time. The new logger system in Python 2.3 has a similar but simpler set of levels. All of these can be used to your advantage as a developer to track data not only at development time, but after deployment. If something funny is happening, ratchet down the log level to show all of your trace/debug/etc messages. It's better than peppering code with print statements whose behavior in a server situation is difficult to predict.