classification
Title: PEP8 arithmetic operator examples
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: gvanrossum Nosy List: docs@python, eric.araujo, ezio.melotti, gvanrossum, pwuertz, rhettinger, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2012-10-15 12:55 by pwuertz, last changed 2012-10-28 20:38 by gvanrossum. This issue is now closed.

Files
File name Uploaded Description Edit
issue16239.diff ezio.melotti, 2012-10-25 17:20
Messages (13)
msg172965 - (view) Author: Peter Würtz (pwuertz) Date: 2012-10-15 12:55
I think the PEP8 examples for arithmetic expressions are a bit misleading. (http://www.python.org/dev/peps/pep-0008/#id20)

The text clearly says that it should add spaces around operators of low(est) priority, which means that I'm encouraged to visually group an expression of high priority. It doesn't say (anymore?) that there should always be spaces around all arithmetic operators.

This is however not reflected in the examples. In the examples
"x = x*2 - 1" is listed as a negative example, while being perfectly compliant with the guide. Shouldn't this be in the "Yes" or an "Optionally" example block?

I believe these examples may cause some people to interpret the style guide in a very rigid way, eventually leading to PEP8 formatting tools that flatten out nicely grouped expressions.
msg173009 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-10-16 01:44
>  Shouldn't this be in the "Yes" 
> or an "Optionally" example block?

+1
msg173770 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-25 17:20
Attached a patch that modifies some of the example in the section.

-      x = x * 2 - 1
-      hypot2 = x * x + y * y
+      x = x*2 - 1
+      hypot2 = x*x + y*y

Here I used more space around operators with lower priority.

-      x = x*2 - 1
-      hypot2 = x*x + y*y
-      c = (a+b) * (a-b)
+      x = x * 2-1
+      hypot2 = x*x + y * y
+      c = a+b * a-b

These 3 examples in the "No" section show respectively:
1) more space around the operator with higher priority;
2) inconsistent spacing around operators with the same priority;
3) misleading spacing (similar to 1);

I don't think it's necessary to mention 'x * 2 - 1' in either sections, because it's not wrong, but otoh 'x*2 - 1' is a better alternative.
msg173776 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-25 17:41
>-      x = x * 2 - 1
>-      hypot2 = x * x + y * y

Why you remove this?

>-      c = (a+b) * (a-b)
>+      c = a+b * a-b

This changes the semantic.

>but otoh 'x*2 - 1' is a better alternative.

Can you justify this?
msg173778 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-25 17:50
> >-      x = x * 2 - 1
> >-      hypot2 = x * x + y * y
>
> Why you remove this?

As I explained in my previous message, even if valid, these are IMHO less clear than x*2 - 1 and x*x + y*y.

> >-      c = (a+b) * (a-b)
> >+      c = a+b * a-b
>
> This changes the semantic.

It does indeed, but I think it's worth pointing out that misleading spacing should be avoided.  Maybe a different example could be used.

> >but otoh 'x*2 - 1' is a better alternative.
>
> Can you justify this?

x*2 - 1  gives a visual hint of what gets executed first,
x * 2-1  gives a wrong/misleading hint of what gets executed first,
x * 2 - 1 gives no hint at all.

I think that providing the correct hint is better than not providing any hints (and clearly better than providing the wrong hint!).
msg173783 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-25 18:04
> As I explained in my previous message, even if valid, these are IMHO less clear than x*2 - 1 and x*x + y*y.

I don't feel this.  Anyone else feel this?  It seems to me, this is a serious change in the Style Guide.

> It does indeed, but I think it's worth pointing out that misleading spacing should be avoided

I think this example shows that even without misleading such spacing is not good.  The destructiveness of misleading spacing is evident for all.
msg173785 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-25 18:11
As I see it:
For  c = (a + b) * (a - b)  the hint (and the actual priority) is given by the (), the spaces around the +/- are not necessary but don't affect readability.
For  c = (a+b) * (a-b)  the hints are given both by the () and the spacing, the lack of spaces around the +/- is not necessary but doesn't affect readability.
For  c = a+b * a-b  the hints are given both by the spacing and they are wrong.
msg173856 - (view) Author: Peter Würtz (pwuertz) Date: 2012-10-26 15:46
>> x * 2 - 1 is less clear than x*2 - 1
> I don't feel this.  Anyone else feel this? 

I strongly feel so. And if you don't take my word for it, just open any math book or look at any formula and recognize that it is the general consensus that the elements of a product are written close together whereas the spacing between two summands is considerably larger. Typically, the dots between products are omitted to reduce the spacing even further.

Trying to educate people to do otherwise is just weird, isn't it?

> It seems to me, this is a serious change in the Style Guide.

Actually it isn't. Even the current style guide says that there should be an increased amount of spacing around operators of low(est) priority. The serious change happened when the old rule "always use exactly one space around all arithmetic operators" fell, which certainly was a good call.

I've seen arguments on mailing lists whether to use x ** 2 + 1 instead of x**2 + 1 based on that rule. I hardly doubt that anyone prefers x ** 2 + 1 over x**2 + 1, so neither should the style guide.
msg173990 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2012-10-28 01:59
Wow.  Someone edited that to be completely against my guidance.  I'll fix it according to my intentions.
msg173991 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2012-10-28 02:05
Corrected to:

  Yes::

      i = i + 1
      submitted += 1
      x = x*2 - 1
      hypot2 = x*x + y*y
      c = (a+b) * (a-b)

  No::

      i=i+1
      submitted +=1
      x = x * 2 - 1
      hypot2 = x * x + y * y
      c = (a + b) * (a - b)
msg174006 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-28 07:41
Thanks!

FTR, this is the changeset: http://hg.python.org/peps/rev/16dd63848921
msg174076 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-28 20:32
One idiom is not covered by the examples:  value = seq[something+1]
IMO it feels weird to put spaces in an index/slice notation.
msg174077 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2012-10-28 20:38
That example doesn't feel strong enough to me to include in the style guide. I am fine with leaving that up to the individual contributor to decide.
History
Date User Action Args
2012-10-28 20:38:24gvanrossumsetmessages: + msg174077
2012-10-28 20:32:17eric.araujosetnosy: + eric.araujo
messages: + msg174076
2012-10-28 07:41:10ezio.melottisetmessages: + msg174006
stage: patch review -> resolved
2012-10-28 02:05:13gvanrossumsetstatus: open -> closed
resolution: fixed
messages: + msg173991
2012-10-28 02:00:15gvanrossumsetassignee: ezio.melotti -> gvanrossum
2012-10-28 01:59:57gvanrossumsetmessages: + msg173990
2012-10-27 20:22:34ezio.melottisetnosy: + gvanrossum
2012-10-26 15:46:56pwuertzsetmessages: + msg173856
2012-10-25 18:11:41ezio.melottisetmessages: + msg173785
2012-10-25 18:04:04serhiy.storchakasetmessages: + msg173783
2012-10-25 17:50:21ezio.melottisetmessages: + msg173778
2012-10-25 17:41:16serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg173776
2012-10-25 17:20:17ezio.melottisetfiles: + issue16239.diff

assignee: docs@python -> ezio.melotti

keywords: + patch
nosy: + ezio.melotti
messages: + msg173770
stage: patch review
2012-10-16 01:44:11rhettingersetnosy: + rhettinger
messages: + msg173009
2012-10-15 12:55:38pwuertzcreate