Lately there has been some efforts to standardize docstrings in SymPy.
The effort has been pretty successful (more info: [1]), but some
questions remain open, so I thought it might be worth asking what the
community thinks. Here are the questions:
1. Should the summary be on the same line as the opening quotes ("""),
or on the next line?
2. Should there be a blank line after every section header?
3. Should the order of sections be predefined or left to the
discretion of the developers.
Here are my preferences:
1. I would put the summary on the same line as the opening quotes. I
use vim folding [3], so when i open a python file, i see only function/
class definitions and the first line of docstrings (because they are
the first line of the new indentation level). Thus i can get quick
overview of a file.
2. I would put a blank line after every section header, because it
makes it more readable.
3. I think that predefined section order is a good thing, because the
consistency makes information easier to find (you know where to look
for it). SciPy/NumPy section order [2] could be used.
Luckily none of these conventions would make developer's work any
harder. Quite the contrary - it is easier to do the right thing if you
know what the right thing is.
[1] https://github.com/sympy/sympy/wiki/Writing-documentation
[2] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
[3] http://vim.wikia.com/wiki/Folding
--
You received this message because you are subscribed to the Google Groups
"sympy" group.
To post to this group, send email to sympy@googlegroups.com.
To unsubscribe from this group, send email to
sympy+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sympy?hl=en.
