Re: [sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-22 Thread Nicolas M. Thiery
On Fri, May 19, 2017 at 06:23:04AM +, Simon King wrote: > X > > In some context, the technical term ``self`` might be easier to > understand (for someone who knows python...) than natural language, > in other context it may be the other way around > > Maybe +1 as a rule of thumb, but -1 as

[sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-19 Thread Simon King
X In some context, the technical term ``self`` might be easier to understand (for someone who knows python...) than natural language, in other context it may be the other way around Maybe +1 as a rule of thumb, but -1 as a strict rule. On 2017-05-17, Kwankyu Lee wrote: >

[sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-18 Thread Marc Mezzarobba
Kwankyu Lee wrote: > G2. Write > > if the lattice is reflexive ... > > but don't write > > if ``self`` is reflexive ... X -- Marc -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from

Re: [sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-17 Thread Jori Mäntysalo
On Wed, 17 May 2017, Andrey Novoseltsev wrote: X I think ``self`` should be allowed in a longer description and allowing it there but not in a one-liner is a bit confusing. So I'd rather not say anything about it and let people use their preferences. I am strongly against X. If we have no

[sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-17 Thread Andrey Novoseltsev
X I think ``self`` should be allowed in a longer description and allowing it there but not in a one-liner is a bit confusing. So I'd rather not say anything about it and let people use their preferences. -- You received this message because you are subscribed to the Google Groups

[sage-devel] Re: Poll for issue G2 a specific guideline for writing docstrings

2017-05-17 Thread Eric Gourgoulhon
+1, although I agree with Travis that ``self`` is technically precise and unambiguous (but for users not familiar with Python, who would read the inline documentation obtained via the question mark, ``self`` can be disturbing) What is the policy of other Python projects regarding this? --