[Tutor] Documentation and top matter

[wormwood_3]

While PEP 8 and PEP 257 provide ample helpful information on the recommended ways to document classes, functions, and comments within code, I am having a hard time finding recommendations on how to document scripts by way of top matter. For example, I used this format for a while:

#!/usr/bin/env python
#-----------------------------------------------------------------------------
# Name:        my_cool_name
# Purpose:     My awesome purpose.
#
# Author:      My Name
#
# Started:     01/01/01
#-----------------------------------------------------------------------------
#
IMPORT STUFF
REST OF CODE

 
This made it *really* easy to see what was going on as soon as you opened the file. Then I started shifting to something more like this:

#!/usr/bin/env python
#-----------------------------------------------------------------------------
"""
My awesome purpose.
"""
author = "My Name"
date_started = "2001-01-01"
version = 0.1 
#-----------------------------------------------------------------------------
IMPORT STUFF
REST OF CODE

This format is still readable and distinct, but by putting the information into attributes, they are accessible in an interpreter, by external tools, etc. Also putting the purpose in the first docstring allowed for use of .__doc__.

But are there more generally accepted means of defining this information that are highly readable? I have also seen attributes in the form of "__author__ = 'My Name'", for which I found some discussion on comp.lang.python ( http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0128.html ).

Recommendations?

_______________________
Samuel Huckins


Homepage - http://samuelhuckins.com
Tech blog - http://dancingpenguinsoflight.com/
Photos - http://www.flickr.com/photos/samuelhuckins/
AIM - samushack | Gtalk - samushack | Skype - shuckins
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/tutor/attachments/20090104/f1590aa3/attachment.htm>