++ I also believe the requirements to:
a) Have a single-line <80 characters brief description AND a long description b) Start the description on the same line as the beginning """ are silly. I think this: """ This is a description, long or short, of what the thing does. It doesn't have to have any particular length or lack of length :param some_param: Description of param """ Is more readable than: """This is a description, artificially limited to 80 characters for som This is a longer description that doesn't really need to be here. :param some_param: Description of param """ -jay On Fri, Oct 21, 2011 at 1:29 PM, Kevin L. Mitchell <[email protected]> wrote: > Our HACKING includes this requirement for multiline docstrings: > > [...] After you have finished your descriptions add an extra > newline and close the quotations. > > I propose that we remove this line and requirement from HACKING. We > don't have to adjust all the docstrings to remove an extraneous space, > but we should not require that it be here. Below is my defense: > > This requirement has never made sense to me, and there does seem to be > some disagreement within nova about following this. So, for more > insight, I went and read PEP 257, and discovered this rationale: > > The BDFL [3] recommends inserting a blank line between the last > paragraph in a multi-line docstring and its closing quotes, > placing the closing quotes on a line by themselves. This way, > Emacs' fill-paragraph command can be used on it. > > (The indicated footnote is just an explanation of the term "BDFL".) > > So, the first point I want to make is that this was a recommendation of > PEP 257, rather than a requirement. The second point is that it was due > to a limitation of the fill-paragraph command of a single editor. And > the third point is that the editor in question, which happens to be my > editor of choice, no longer has this limitation, at least in recent > versions--fill-paragraph on docstrings terminated by triple-quotes > ignores the triple-quotes. Therefore, I believe the recommendation no > longer has any substance behind it, and so it should no longer be > required of HACKING-conforming code for nova. > -- > Kevin L. Mitchell <[email protected]> > > This email may include confidential information. If you received it in error, > please delete it. > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : [email protected] > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : [email protected] Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp

