line length in docstring and tests

[Reimundo Heluani]

Hello, in the developer's guide

https://doc.sagemath.org/html/en/developer/coding_basics.html#documentation-strings

It says explicitly that lines should be shorter than 80 characters:

"Lines should be shorter than 80 characters. If in doubt, read PEP8: Maximum
Line Length."


That PEP8 further says that

"For flowing long blocks of text with fewer structural restrictions
(docstrings or comments), the line length should be limited to 72 characters."

My question is about indented code in examples as these examples serve two
purposes: doctesting and documentation. If I wrap text at 80 or 72 characters
for long lines of output, the test part as in

sage -t src/sage/mypatch.py

still works. But the rendering of the HTML has an incorrect CR.

I've looked through the code and found numerous instances of long times in
examples and tests blocks. So my question is: is there a policy about these
things? My guess is to leave the long lines of output without wrapping.

Best,

R.

[Michael Orlitzky]

On 5/30/20 8:51 AM, 'Reimundo Heluani' via sage-devel wrote:
>
> I've looked through the code and found numerous instances of long times in
> examples and tests blocks. So my question is: is there a policy about these
> things? My guess is to leave the long lines of output without wrapping.
>

You can usually add parentheses and continue your doctest with a "....:"
on the next line so that the test retains its meaning and the HTML
output remains correct. For example, here's a line that's too long:

> sage: from mjo.eja.eja_algebra import QuaternionMatrixEuclideanJordanAlgebra

Instead of forcing a line break with (say) a backslash, you can do

sage: from mjo.eja.eja_algebra import (
....: QuaternionMatrixEuclideanJordanAlgebra )

The same trick allows you to break sums, products, list comprehensions,
etc. over multiple lines.

[Reimundo Heluani]

Thanks, my question is mainly about output strings, how do you break them with
ellipsis?

R.

>
>--
>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+...@googlegroups.com.
>To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/9cbbc443-97e8-deec-d29d-cab5976f3cfd%40orlitzky.com.

[John H Palmieri]

Lines should be shorter than 80 characters when possible. If it isn't possible because it will cause confusion, break a doctest, make a doctest unhelpful, etc., then you can make an exception. There are plenty of exceptions in the Sage library already, for example

https://git.sagemath.org/sage.git/tree/src/sage/homology/chain_complex.py#n225

(I just picked a file at random in the Sage library and found an example. I would guess that this is typical.)

Ellipses in doctest output should be used for parts of the output that are random or are too long (as in many lines long) to be useful. The details of the traceback from an error is a typical use case for this.

On Saturday, May 30, 2020 at 6:31:34 AM UTC-7, Reimundo Heluani wrote:

On May 30, Michael Orlitzky wrote:
>On 5/30/20 8:51 AM, 'Reimundo Heluani' via sage-devel wrote:
>>
>> I've looked through the code and found numerous instances of long times in
>> examples and tests blocks. So my question is: is there a policy about these
>> things? My guess is to leave the long lines of output without wrapping.
>>
>
>You can usually add parentheses and continue your doctest with a "....:"
>on the next line so that the test retains its meaning and the HTML
>output remains correct. For example, here's a line that's too long:
>
>> sage: from mjo.eja.eja_algebra import QuaternionMatrixEuclideanJordanAlgebra
>
>Instead of forcing a line break with (say) a backslash, you can do
>
>  sage: from mjo.eja.eja_algebra import (
>  ....:     QuaternionMatrixEuclideanJordanAlgebra )
>
>The same trick allows you to break sums, products, list comprehensions,
>etc. over multiple lines.
>
Thanks, my question is mainly about output strings, how do you break them with
ellipsis?

R.

>
>--
>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-...@googlegroups.com.

[John H Palmieri]

It seems that over 80% of the files in the Sage library have lines longer than 80 characters, and about 50% of files have lines in doctests which are longer than 80 characters.

[Reimundo Heluani]

On May 30, John H Palmieri wrote:
>Just for kicks, I counted the number of .py and .pyx files in the Sage library,
>and then counted the ones with lines longer than 80 characters in their
>docstrings/doctests. 84% of them had such lines.
>
Thanks, that was my impression, I looked and looked and found tons of long
lines and I don't remember one example of a broken output line (that would
render ugly but still pass a doctest).

Perhaps this could be added to the developer's guide. I started working on vim
with the little annoyance of having two different colorcolumns (at 72 and 80)
just because of that PEP, but I suspect that no one cares about the different
line lenghts (admittedly this is just an unfounded hunch).

Best,

R.

>
>On Saturday, May 30, 2020 at 9:14:59 AM UTC-7, John H Palmieri wrote:
>

> Lines should be shorter than 80 characters when possible. If it isn't
> possible because it will cause confusion, break a doctest, make a doctest
> unhelpful, etc., then you can make an exception. There are plenty of
> exceptions in the Sage library already, for example
>

> [1]https://git.sagemath.org/sage.git/tree/src/sage/homology/
> chain_complex.py#n225

> >[2]https://groups.google.com/
> d/msgid/sage-devel/9cbbc443-97e8-deec-d29d-cab5976f3cfd%40orlitzky.com.

>
>--
>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 [3]sage-devel+...@googlegroups.com.

>To view this discussion on the web visit

>[4]https://groups.google.com/d/msgid/
>sage-devel/9cd7f65c-c9bc-41de-a93b-cbd45639dcf1%40googlegroups.com.
>
>References:
>
>[1]
>https://git.sagemath.org/sage.git/tree/src/sage/homology/chain_complex.py#n225
>[2]
>https://groups.google.com/d/msgid/sage-devel/9cbbc443-97e8-deec-d29d-cab5976f3cfd%40orlitzky.com
>[3] mailto:sage-devel+...@googlegroups.com
>[4]
>https://groups.google.com/d/msgid/sage-devel/9cd7f65c-c9bc-41de-a93b-cbd45639dcf1%40googlegroups.com?utm_medium=email&utm_source=footer

[Michael Orlitzky]

On 5/30/20 9:25 AM, 'Reimundo Heluani' via sage-devel wrote:
>
> Thanks, my question is mainly about output strings, how do you break them with
> ellipsis?
>

Oh, I don't know. I break them manually and let the line breaks show up
in the HTML. Users may see wrapped output anyway from either the width
of their terminals or the width of their browsers, so I don't think it's
a huge problem if the HTML example output contains extra breaks.

Do whatever you think is best?

[Volker Braun]

I'm with Linus in that the 80 characters limit is an anachronism thats too restrictive in a time and age where large high-resolution displays are ubiqitous. There certainly is a "too long" somewhere but its more in the 100-character region.

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bdc48fa11e46f867ea4d75fa59ee87a7f48be144

[Michael Orlitzky]

You shouldn't force yourself to stick to 80 characters when there's a
technical reason for the line to be longer, but the argument for the
80-character limit is not some fairy tale about punch cards or
PDP-11/VAX terminals. Find a book. How long are the lines? They're
roughly the length that millennia of "user interface" research has
taught us is most comfortable to read. Depending on the font, the max is
around 80.

[Reimundo Heluani]

I didn't mean to start an argument about line length. I am about to submit a
very large patch and if I ever hope to get a reviewer, I want to adhere as
much as possible to whatever code style is imposed. I wanted to get a feeling
if people really expected PEP8 as stated in the Developer's guide or not.
Particularly about length 72 on output strings of tests and examples. It seems
that I got my answer and it seems to be that it won't be an issue to leave
these lines. As of now my code is a mess, but it's slowly improving.

Best,

R.



>
>--
>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+...@googlegroups.com.
>To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/9fabe31a-0ad8-c0a3-7837-bb8e18a7a63f%40orlitzky.com.

[Nils Bruin]

On Tuesday, June 2, 2020 at 10:13:55 AM UTC-7, Michael Orlitzky wrote:

You shouldn't force yourself to stick to 80 characters when there's a
technical reason for the line to be longer, but the argument for the
80-character limit is not some fairy tale about punch cards or
PDP-11/VAX terminals. Find a book. How long are the lines? They're
roughly the length that millennia of "user interface" research has
taught us is most comfortable to read. Depending on the font, the max is
around 80.

True, but indent space does not  really eat into the readability there. With 3 to 4 levels of 4-space indent (not uncommon in python), you're at 80+16=96; pretty close to 100.

One of the reasons for limited line length (and that's also an argument for column-formatting such as in news papers) is that the right-to-left tracking the human eye has to do from one line to the next is more difficult for lines that are way longer than they are high (so: same reason why tables often have alternating backgrounds across their rows).

Computer code has plenty of other cues for line separation too, so I'm not sure the same guidance that applies to body text translates to computer code unchanged.