[ovs-dev] [python idl 12/16] ovs.ovsuuid: Get rid of ovs.ovsuuid.UUID class.

[Ben Pfaff]

On Mon, Sep 19, 2011 at 06:13:52PM -0700, Ethan Jackson wrote:
> Please use two newlines between top level definitions.

OK, done.

> I think we need to decide on an OVS style for python docstring
> comments.  I've looked at both the google style and this one:
> http://www.python.org/dev/peps/pep-0257/
> 
> I do like the following suggestion that both of them recommend:  The
> first line of a function docstring should be a short sentence,
> followed by a more detailed paragraph separated by a newline.  Pep 257
> says that this helps automatic indexing tools.  I'm not sure we want
> to get into prescribing exactly what should be documented and how.
> 
> Since we don't have a style, the current code is fine.  Just curious
> if you have an opinion on this subject.

Do I have an opinion?  Ha!  Personally I think that most of the styles
I've seen for function documentation are nonsense.  The documentation
is close to worthless, and I end up having to look at the source code
anyway.

First, there is often a huge amount of redundancy.  There's a title
that says what the function does, there's an extended description that
says the same thing (maybe adding a word or two or a sentence),
there's a description of every single parameter that duplicates half
of what the description says, and then there's a description of the
return value that duplicates half of it again.

Worst of all, all of this stupid redundant description lets developers
think that, just because they filled in every little field in the
form, they actually explained what the function does well.  And that's
often just not true.

There's basically no way I'm going to adopt a docstring style that
encourages any of these flaws.

If it's a matter of how docstrings should formatted or indented or
whatever, that's a separate issue.  I don't care much; I'm willing to
adopt any reasonable style.