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