[New-bugs-announce] [issue43034] Python tutorial misleads users about floor division behavior

[Jesse Silverman]

New submission from Jesse Silverman <jessevsilverman at gmail.com>:

I had never worked thru the Python tutorial, it's kind of awesome.

I noticed multiple independent presenters incorrectly describe the behavior of floor division when the signs of the operands don't match.  Not just sloppy ones, some who are usually pretty careful -- people forget.  I found it odd.

Today I read:
https://docs.python.org/3.9/tutorial/introduction.html#using-python-as-a-calculator
'Division (/) always returns a float. To do floor division and get an integer result (discarding any fractional result) you can use the // operator; to calculate the remainder you can use %:'

I know what they mean (there will never be a non-zero fractional component in the result) however, stating that it "discards any fraction result" explicitly suggests that it will round towards zero for all results.  The name of the operator tells us the true story, as does a test, it rounds towards negative infinity for all results.

Hopefully all the people using Python to treat cancer, fly to Mars and run power plants know what the behavior is.  However, anecdotally, I have seen evidence that generally cautious, fairly-detail oriented programmers seem to forget the details of the behavior, this is one place in the docs from which many people first learn about the floor division operator and this page would lead me to believe it operates differently than it does in reality.

If the words right there don't get changed, or the example of -10/3 doesn't get added, would this be a good excuse for a third footnote?  I would actually wish for both the wording to be changed and to show an example like -10 / 3, tho admittedly I came from an Engineering background so I am always worried someone's going to blow up somewhere...

Deepest regards for everyone who gets to regularly close the complaints about floor division working as designed and documented -- but not quite documented on this page which more people may read than others covering the operator.

----------
assignee: docs at python
components: Documentation
messages: 385746
nosy: docs at python, jessevsilverman
priority: normal
severity: normal
status: open
title: Python tutorial misleads users about floor division behavior
versions: Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43034>
_______________________________________