Second round poll for H5 a specific guideline for writing docstrings

[Kwankyu Lee]

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.

[David....@inria.fr]

A method like `Graph().is_bipartite(certificate=False)` returns either ``True``or ``False`` when ``certificate==False``, or a tuple `(bool, dict)` when ``certificate==True``. What would be the recommended writing style for the output block ?

[Jeroen Demeyer]

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

[Simon King]

+1

On 2017-05-18, Kwankyu Lee <ekwa...@gmail.com> wrote:
> 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.*
> *----*

[Daniel Krenn]

+1 for this option

[chris wuthrich]

-1

I am with Jeroen on this one.

[Jori Mäntysalo]

My suggestion would be

OUTPUT:

- If ``certificate=True`` return only True or False.
- If ``certificate=False`` return either
* (True, XX), where XX is...
* (False, XX), where XX is...

and when there is only one-way certificate,

OUTPUT:

- If ``certificate=True`` return only True or False.
- If ``certificate=False`` return either (True, None) or (False, XX),
where XX is...

--
Jori Mäntysalo

[Kwankyu Lee]

+1

H5 is intended to be conforming with "INPUT:" block. 

The above example is somewhat misleading. If the output is just a "tuple of lattices" (without long additional explanation), then the entire OUTPUT block can be omitted since the one-liner can be "Return a tuple of lattices that ....". 

[Sébastien Labbé]

My suggestion would be

OUTPUT:

- If ``certificate=True`` return only True or False.
- If ``certificate=False`` return either
   * (True, XX), where XX is...
   * (False, XX), where XX is...

 

I think this is too much information which will overlap with the INPUT block or even a small paragraph that goes before the INPUT block, that explains the certificate stuff. The only thing I want to see in the OUTPUT block is the *type* of the objects and how many of them.

So in the ultra rare case of output type or length depending on some flag, I would go for:

OUTPUT: boolean or a 2-tuple (boolean, XX) if certificate is True

In all other case and in particular for what is suggested for the guideline which will apply to almost all cases, I would go +1 for H5 (or +1 for Jeroen's shorter suggestion. I don't really mind actually).

Sébastien

[Johan S. H. Rosenkilde]

> 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).

[Jori Mäntysalo]

On Fri, 19 May 2017, Sébastien Labbé wrote:

> My suggestion would be
>
> OUTPUT:
>
> - If ``certificate=True`` return only True or False.
> - If ``certificate=False`` return either
>    * (True, XX), where XX is...
>    * (False, XX), where XX is...
>  
> I think this is too much information which will overlap with the INPUT block
> or even a small paragraph that goes before the INPUT block, that explains
> the certificate stuff. The only thing I want to see in the OUTPUT block is
> the *type* of the objects and how many of them.

I should see a whole example to be able to comment this. We can have
longer INPUT and shorter OUTPUT, or vice versa.

--
Jori Mäntysalo

[Michael Orlitzky]

We should outlaw the practice, and anyone who enjoys using MATLAB =)

[Jeroen Demeyer]

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 ...

[Jeroen Demeyer]

On 2017-05-19 14:16, Jori Mäntysalo wrote:
> The only thing I want to see in the OUTPUT
> block is
> the *type* of the objects and how many of them.

Why that? What's wrong with being verbose in the OUTPUT block?

I would like something like

INPUT:

- ``certificate`` -- boolean; whether to output a certificate, see OUTPUT

OUTPUT:

- If ``certificate=False``: a boolean

- If ``certificate=True``: something more complicated

[Jori Mäntysalo]

On Mon, 22 May 2017, Jeroen Demeyer wrote:

> On 2017-05-19 14:16, Jori Mäntysalo wrote:

>> The only thing I want to see in the OUTPUT block is the *type* of the
>> objects and how many of them.
>
> Why that? What's wrong with being verbose in the OUTPUT block?

This is a misquote. I support something like you suggested in this mail.

--
Jori Mäntysalo

[Jeroen Demeyer]

On 2017-05-22 11:35, Jori Mäntysalo wrote:
>> Why that? What's wrong with being verbose in the OUTPUT block?
>
> This is a misquote.

I meant to reply to Sébastien Labbé.

[Kwankyu Lee]

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.

 

[Jeroen Demeyer]

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.

[Jeroen Demeyer]

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.

[Kwankyu Lee]

The non-redundant information will be implied by the list of hyphened items, if we stick to the convention. 

[Jeroen Demeyer]

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!

[Daniel Krenn]

+1 for "a tuple" in this case (and not skipping this information; it is
essential)

[Jori Mäntysalo]

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

[Sébastien Labbé]

On Monday, May 22, 2017 at 10:27:28 AM UTC+2, Jeroen Demeyer wrote:

> The only thing I want to see in the OUTPUT
> block is
> the *type* of the objects and how many of them.

Why that? What's wrong with being verbose in the OUTPUT block?

The OUTPUT block appearing below other, I think we do not want to impose that OUTPUT block get so verbose that it just repeat information that appeared above it. Of course, if something needs to be verbosed at that point following the information that was/was'nt given before, then yes, I think being verbose to clarify something not explained before is okay.

[Kwankyu Lee]

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?

[Vincent Delecroix]

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.

[Kwankyu Lee]

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.