[Openstack] Proposed amendment to HACKING
Ed Leafe
ed.leafe at rackspace.com
Fri Oct 21 18:17:14 UTC 2011
On Oct 21, 2011, at 12:37 PM, Jay Pipes wrote:
> 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.
Unfortunately, many tools that auto-generate documentation from docstrings rely on this convention. I fully agree that it makes for ugly docstrings, but I believe that the purpose is not to make the source code more readable. That's also the reason for the (usually) useless listing of :param elements - those should only be documented if there is something funky about them, and even then you should first reconsider your use cases and design if you can't remove the funkiness.
-- Ed Leafe
This email may include confidential information. If you received it in error, please delete it.
More information about the Openstack
mailing list