Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings
'Return whether...' is broken English anyway, at least IMHO. 'True if X prime, otherwise False' reads much better. in fact, the correct X may be inserted by the online help system. as well, for a function is_bla() such a string may be generated, no need to even have it physically in the docs. Dima -- 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 it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings
(2) -- 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 it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings
On 2017-05-20 00:03, Kwankyu Lee wrote: > This is my last attempt to save the guideline. > > A Sage user has an integer X. He hit the tab key and get "X.is_prime", > and then ask what this method does by entering "X.is_prime?". Imagine > that he reads > > (1) Return whether the integer is prime. > > (2) Return whether this integer is prime. > > (3) Return whether ``self`` is prime. > > Which one of these is most friendly plain English answer to his question? (2) -- 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 it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings
This is my last attempt to save the guideline. A Sage user has an integer X. He hit the tab key and get "X.is_prime", and then ask what this method does by entering "X.is_prime?". Imagine that he reads (1) Return whether the integer is prime. (2) Return whether this integer is prime. (3) Return whether ``self`` is prime. Which one of these is most friendly plain English answer to his question? -- 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 it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
Re: [sage-devel] Re: Second round poll for H2 a specific guideline for writing docstrings
On 19/05/2017 20:39, kcrisman wrote: On Thursday, May 18, 2017 at 10:29:42 PM UTC-4, Travis Scrimshaw wrote: Strong -1 (still) Even though this is something confusing to newcomers, I think that I have to agree with Travis. That said, I don't see why one couldn't just say "if ``self`` (the lattice) is reflexive". Much harder to read than the two versions "self" vs "the lattice"! In the one line description I tend to think that we can have additional information using "this X" rather than self, eg def is_prime(self): "Test whether this integer is prime" versus def is_prime(self): "Test whether ``self`` is prime" In the rest of the docstring, it might be a good practice to use ``self`` especially when algorithmic considerations are given. For example """ Test whether this integer is prime If ``self`` is more than 8000 bits we use some nice heuristic from outer space. """ Vincent -- 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 it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
