[sugar] Python Style Guide

[Ian Bicking]

Marco Pesenti Gritti wrote:
> 
>>
>> >For simple public data attributes, it is best to expose just the 
>> attribute name, without complicated >accessor/mutator methods
>>
>> I'm not sure I like this... It's quite unusual for non python coders. 
>> If we want to keep it we should probably elaborate more on it in the 
>> guide.
> 
> 
> With this method, how do you find out which attributes are supported 
> other than by reading the code? Is there a way to document them?
> 
> /me should probably just read about python attributes

You can do dir(obj) to get a list of attributes and functions.

There's a couple other ways to do documentation:

* If it's a property (a dynamic attribute) you can add a docstring. 
Some (but sadly not many) tools know how to read this.

* If it's a class attribute, some documentation extractors will read 
preceding comments or strings.  For instance attributes you can place a 
default value as the class attribute.

* help() apparently is stupid and doesn't work on instances.  This 
surprises me.  It will show class attributes when you get the help for a 
class.

* You can create an interface, which is an abstract description for an 
object.  There are conventions for how to represent attributes there, 
that includes documentation.

* Obviously free-form documentation always works; e.g., put it in the 
class docstring.

-- 
Ian Bicking | ianb at colorstudy.com | http://blog.ianbicking.org