On Thu, 22 May 2014, Jiri Kuncar wrote: > After integrating PEP8 and PEP257 style guides for Python code,
WRT PEP 257, this is still under discussion: https://forum.invenio-software.org/t/is-pep257-good-for-you/39/11 as it seems nobody followed up since my last comment? Standardising on PEP 257 alone, without standardising on unified parameter documentation, would be much less advantageous in my eyes... * * * Otherwise, a tongue-in-cheek note for all the vimers out here. When writing Lisp code, starting multi-line docstrings with one-line headline summary is *exactly* how Emacs Lisp coding conventions go. The headline should be understandable standalone and is then used as a function summary in various places, such as by the `apropos` command. Hence doing the same in Python would make perfect sense to Emacsers. Moreover it would create a nice analogy between Python docstrings and Git commit log messages that one starts with one-line headline summary already. (Note that I'm reusing git commit log headlines later "as they are" when compiling release notes -- which is one of the reasons why we are paying so much attention for having clear, self-contained, self-understandable commit log headlines.) So, while personally I'm in favour of standardising upon PEP 257 docstring style, I'd like to tackle a very closely related question of moving-away-from-epytext-to-a-sphinx-autodoc-friendly-reST-format at the same time, too. (see my above Forum discussion post) Once we have a consensus there, we can close that opened RFC thread and document the decision. Best regards -- Tibor Simko
