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. _______________________________________________ dev mailing list [email protected] http://openvswitch.org/mailman/listinfo/dev
