Re: [sage-devel] Second round poll for H5 a specific guideline for writing docstrings
On Monday, May 22, 2017 at 2:41:17 PM UTC+2, vdelecroix wrote: > > > Yes! A function in Python always return a unique object. This object > might be a tuple or a list with several components. Ok. Now I understand how you view things. I always thought it is a common idiom in Python that when the output consists of several items, then the output is a tuple of those items (so Python supports this idiom by allowing "Return a,b,c" rather than "Return (a,b,c)"). If you think there is always a choice between a tuple or a list when you return several items, expressing this explicitly in the docstring is essential. -- 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] Second round poll for H5 a specific guideline for writing docstrings
On 22/05/2017 14:35, Kwankyu Lee wrote: It seems that some misunderstanding is going on here. If a method returns an integer and a matrix by "Return n, m". I am saying that the output block can be simply OUTPUT: - integer ... - matrix ... instead of OUTPUT: a tuple of ``(n,m)`` where - ``n`` is a integer ... - ``m`` is a matrix ... You may prefer the second style, but does the first style miss an essential information? Yes! A function in Python always return a unique object. This object might be a tuple or a list with several components. So I would say that it is mandatory to specify what the actually output is. In the above case a tuple. Compare def f(): return 1,2 def g(): return [1,2] The functions has essentially the same functionalities however these are different functions. -- 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] Second round poll for H5 a specific guideline for writing docstrings
It seems that some misunderstanding is going on here. If a method returns an integer and a matrix by "Return n, m". I am saying that the output block can be simply OUTPUT: - integer ... - matrix ... instead of OUTPUT: a tuple of ``(n,m)`` where - ``n`` is a integer ... - ``m`` is a matrix ... You may prefer the second style, but does the first style miss an essential information? -- 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] Second round poll for H5 a specific guideline for writing docstrings
On Mon, 22 May 2017, Daniel Krenn wrote: My opinion is that the phrase "a tuple `(a,b,c)` where ..." is just redundant. I think that "a tuple" is important non-redundant information. +1 for "a tuple" in this case (and not skipping this information; it is essential) +1 from me too. Something printed (a, b, c) might actually be something more complicated that a plain tuple. -- Jori Mäntysalo
Re: [sage-devel] Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-22 12:08, Jeroen Demeyer wrote: > On 2017-05-22 12:05, Kwankyu Lee wrote: >> My opinion is that the phrase "a tuple `(a,b,c)` where ..." is just >> redundant. > > I think that "a tuple" is important non-redundant information. +1 for "a tuple" in this case (and not skipping this information; it is essential) -- 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] Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-22 12:21, Kwankyu Lee wrote: The non-redundant information will be implied by the list of hyphened items, if we stick to the convention. So, in order to understand the docstring, the user needs to read the docstring and the convention on how to read the docstring. Not good! -- 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] Second round poll for H5 a specific guideline for writing docstrings
On Monday, May 22, 2017 at 12:08:35 PM UTC+2, Jeroen Demeyer wrote: > > On 2017-05-22 12:05, Kwankyu Lee wrote: > > My opinion is that the phrase "a tuple `(a,b,c)` where ..." is just > > redundant. > > I think that "a tuple" is important non-redundant information. > The non-redundant information will be implied by the list of hyphened items, if we stick to the convention. -- 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] Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-22 12:05, Kwankyu Lee wrote: My opinion is that the phrase "a tuple `(a,b,c)` where ..." is just redundant. I think that "a tuple" is important non-redundant information. -- 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] Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-22 12:05, Kwankyu Lee wrote: This is ugly. By your previous opinion, wouldn't you prefer this? | OUTPUT:a tuple of ``(a,b,c)``where -``a``is... -``b``is... -``c``is... | I think that the guideline of this thread combined with your one-liner style for OUTPUT allows this. Of course, this is much better. -- 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] Second round poll for H5 a specific guideline for writing docstrings
On Monday, May 22, 2017 at 10:24:32 AM UTC+2, Jeroen Demeyer wrote: > > I very much object to this: > > > If the output consists > > of several items, add each starting with a hyphen. > > If the output consists of several items, the OUTPUT string should > clearly mention that fact (and it should mention whether the output is a > tuple or list or some other structure with several items). > To be clear, I meant the case that the output is by Return a, b, c My opinion is that the phrase "a tuple `(a,b,c)` where ..." is just redundant. Anyway I guess that different people have different opinions about this as well. > So something like: > > OUTPUT: > > - a tuple `(a,b,c)` where > >- ``a`` is ... > >- ``b`` is ... > >- ``c`` is ... > This is ugly. By your previous opinion, wouldn't you prefer this? OUTPUT: a tuple of ``(a,b,c)`` where - ``a`` is ... - ``b`` is ... - ``c`` is ... I think that the guideline of this thread combined with your one-liner style for OUTPUT allows this. -- 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] Second round poll for H5 a specific guideline for writing docstrings
I very much object to this: If the output consists of several items, add each starting with a hyphen. If the output consists of several items, the OUTPUT string should clearly mention that fact (and it should mention whether the output is a tuple or list or some other structure with several items). So something like: OUTPUT: - a tuple `(a,b,c)` where - ``a`` is ... - ``b`` is ... - ``c`` is ... -- 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] Second round poll for H5 a specific guideline for writing docstrings
> As I mentioned on the other thread, since OUTPUT is not a list of things > (as opposed to INPUT), I would prefer > > OUTPUT: tuple of lattices +1 on this option (and hence -1 to the thread's suggestion). -- 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] Second round poll for H5 a specific guideline for writing docstrings
On 2017-05-19 08:57, Jeroen Demeyer wrote: > As I mentioned on the other thread, since OUTPUT is not a list of things > (as opposed to INPUT), I would prefer > > OUTPUT: tuple of lattices +1 for this option -- 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] Second round poll for H5 a specific guideline for writing docstrings
As I mentioned on the other thread, since OUTPUT is not a list of things (as opposed to INPUT), I would prefer OUTPUT: tuple of lattices -- 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.
[sage-devel] Second round poll for H5 a specific guideline for writing docstrings
Hi, I prepared H5 revised from G5 based on your ideas and wishes. It was hard to make a compromise from your differing opinions and reach a proposal for the better. So this time* if I fail to get approval from most of you, the guideline will be simply discarded.* ** H5. Write OUTPUT: - tuple of lattices Note the leading hyphen and no period at the end. If the output consists of several items, add each starting with a hyphen. If you agree, flag +1; if you don't, flag -1. -- 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.
