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.