Style questions

[James Mills]

David,

Here's a "good" example (NB: subjective):

http://hg.softcircuit.com.au/index.wsgi/circuits/file/251bce4b92fd/circuits/core.py

On Fri, Oct 24, 2008 at 10:04 AM, David Di Biase <dave.dibiase at gmail.com> wrote:
> I have a few simple questions regarding python style standards. I have a
> class contained in a module...I'm wondering if I should perform any imports
> that are relevant to the class within the constructor of the class or at the
> top of the module page.

Normally imports are conventionally done at the top of the module.
Within the module's scope.
Some people import the entire module while others
import only bits that they need.

> Also if I'm creating a docstring for the class I should list all my public
> methods, should I just list them or should I just summarise what they do?
> ie:
>
>     """Displays a graphical game of variant of Connect4.
>        Supports two players on a 6x7 game board.
>
>        Public methods:
>        __init__()
>        clear_screen()
>        draw_header()
>        draw_board()
>        play()
>        prompt_for_move()
>
>     """

Don't write what can be easily dispalyed
with pydoc or some other documentation tool.
The methods are already clearly there.
See my core.py above.

> Last question, sometimes I have a simple function with no keyword arguments
> and returns none. According to the styleguide we are to include return None
> at the end of the function regardless, so should I also explicitly state
> that the function returns this in the one line description? ie:

Not generally. Most python developers
know that functions that do not have a return
statement, actually implicitly returns None.

You're documenting for developers (python developers) not users.

cheers
James

-- 
--
-- "Problems are solved by method"