Poll for issue G1 a specific guideline for writing docstrings

[Kwankyu Lee]

We do a poll for adopting an official guideline for docstrings (see https://trac.sagemath.org/ticket/23017)

--------

G1. Write 

 

Return True if something is true.

but do not write 

Return ``True`` if something is true.

The same applies to `False` and `None`

--------

If you agree, flag +1; if you disagree and want it reversed, flag -1; if you think we do not need this guideline, flag X. 

[Daniel Krenn]

-1

See the first few lines of [1] where an equivalent of our ``True`` is
used (and therefore written in typewriter font)

Moreover, in the note box above
Section "3.1. Constants added by the site module", it is even done
better and a link to Python's True and False is given. (+1 for linking
True, False, None to these Python sites. IMO this should be the
encouraged way also for Python's exceptions etc.)

[1] https://docs.python.org/3/library/constants.html

[John H Palmieri]

-1. True is literal code and should be highlighted as such in docstrings. Sphinx/reST markup says that double backquotes are used for "code samples", and that's exactly what this is.

--
John

[Volker Braun]

I'd try to avoid the entire construct; Its the linguistic equivalent of

if condition:

     return True

else:

    return False

Just say "Test condition" in the docstring.

[Eric Gourgoulhon]

-1 (typesetting adds readability)

[Andrey Novoseltsev]

-1

[Kwankyu Lee]

-1

See the first few lines of [1] where an equivalent of our ``True`` is
used (and therefore written in typewriter font)

(This is perhaps my last resistance; please bear with me :-) 

A technical question: is it possible to set our Sphinx so that we write in a docstring

Return True if something is False.

but the True and False are rendered in tt font (or even as links as you suggested). Then we could avoid cluttering files with lots of double quotes for True, False, and None, and use them mostly for arguments.

 

[Marc Mezzarobba]

Kwankyu Lee wrote:
> G1. Write
>
> Return True if something is true.
>
> but do not write
>
> Return ``True`` if something is true.
>
> The same applies to `False` and `None`

X

--
Marc

[Erik Bray]

I don't think you could write something that is intelligent enough to
distinguish the literals ``True``, ``False``, or ``None`` with the
word itself (which would be capitalized if beginning a sentence--not
common, but not impossible either).

[Jeroen Demeyer]

On 2017-05-18 14:36, Erik Bray wrote:
> I don't think you could write something that is intelligent enough to
> distinguish the literals ``True``, ``False``, or ``None`` with the
> word itself (which would be capitalized if beginning a sentence--not
> common, but not impossible either).

Reasonable example: "None of the input vertices should be adjacent."

[Simon King]

-1, for reasons that have already been explained by others. Generally,
any reference to a programmatical object should be typographically
distinguished from normal text. Hence, it should be
"Let `f(x)` be the function that returns ``True`` if `x>0` and
``False`` otherwise."
but not
"Let f(x) be the function that returns True if x>0 and False
otherwise."

Cheers,
Simon

[Nicolas M. Thiery]

On Wed, May 17, 2017 at 12:32:47PM -0700, Volker Braun wrote:
> I'd try to avoid the entire construct; Its the linguistic equivalent of
> if condition:
> return True
> else:
> return False
> Just say "Test condition" in the docstring.

Yes, I agree!!! If we want to stick to the "Return ..." idiom, an
alternative is to say "Return whether <condition>".

I guess that's slightly off topic though; I imagine this sentence was
just meant as one example where ``True`` could appear in our doc.

For how to typeset True/False/None/... when we need to spell them out
explicitly, as already suggested, I would be in favor of :obj:`True`.

Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/

[Daniel Krenn]

On 2017-05-23 04:16, Nicolas M. Thiery wrote:
> For how to typeset True/False/None/... when we need to spell them out
> explicitly, as already suggested, I would be in favor of :obj:`True`.

I wasn't aware that this works. But in this case, I am in favor (+1) of
:obj:`True` as well.

Best

Daniel