Is it new style or just lack of style?
Richard Jones
richard at bizarsoftware.com.au
Sun Aug 5 21:09:16 EDT 2001
On Saturday 04 August 2001 03:50, John Schmitt wrote:
> Whitespace is beautiful and my code is art! :-)
mumble .. eye of the beholder .. mumble :)
> If I have a function that takes a few arguments, I lay it out like this:
>
> def foo\
> (
> argument1, # meaninful comments
> argument2,
> ):
> # more beautiful code here
Why wouldn't you insert those meaningful comments into a docstring so that it
can be used by documentation tools? The layout of the function is quite
jarringly different from the "accepted" python style (as described in Guido's
guide of style).
def foo(spam, implement):
'''foo takes a can of spam and applies the implement to it, returning the
result.
spam - the can of spam to operate on
implement - the implement to operate with
This function blah blah blah blah.
'''
Here is a longer example:
def init(instance_home, template, backend, adminpw):
'''Initialise an instance using the named template and backend.
instance_home - the directory to place the instance data in
template - the template to use in creating the instance data
backend - the database to use to store the instance data
adminpw - the password for the "admin" user
The instance_home directory will be created using the files found in
the named template (roundup.templates.<name>). A standard instance_home
contains:
. instance_config.py
- simple configuration of things like the email address for the
mail gateway, the mail domain, the mail host, ...
. dbinit.py and select_db.py
- defines the schema for the hyperdatabase and indicates which
backend to use.
. interfaces.py
- defines the CGI Client and mail gateway MailGW classes that are
used by roundup.cgi, roundup-server and roundup-mailgw.
. __init__.py
- ties together all the instance information into one interface
. db/
- the actual database that stores the instance's data
. html/
- the html templates that are used by the CGI Client
. detectors/
- the auditor and reactor modules for this instance
The html directory is typically extracted from the htmlbase module in
the template.
'''
This information is accessible using pydoc, and is also eminently readable
while perusing the source.
Richard
More information about the Python-list
mailing list