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
_______________________________________________ Tutor maillist - Tutor@python.org http://mail.python.org/mailman/listinfo/tutor
