[docs] [issue31021] Clarify programming faq.

[Terry J. Reedy]

New submission from Terry J. Reedy:

https://docs.python.org/3/faq/programming.html#why-does-22-10-return-3
"Why does -22 // 10 return -3?
It’s primarily driven by the desire that i % j have the same sign as j. If you want that, and also want:

i == (i // j) * j + (i % j)

then integer division has to return the floor. C also requires that identity to hold, and then compilers that truncate i // j need to make i % j have the same sign as i.

There are few real use cases for i % j when j is negative. When j is positive, there are many, and in virtually all of them it’s more useful for i % j to be >= 0. If the clock says 10 now, what did it say 200 hours ago? -190 % 12 == 2 is useful; -190 % 12 == -10 is a bug waiting to bite."

A user noticed that '-190 % 12 == -10' is False, but would be True is '-' were inserted before '12', and posted https://github.com/python/cpython/pull/2768 to correct the presumed typo.

It is not a typo, and I will close the issue, but the text as is is confusing.  I propose replace "-190 % 12 == -10 is" with "if -190 % 12 were the mathematically equivalent -10, it would be" [a bug waiting to bite].  I don't like the 'bug' part because it would not be a bug, exactly, but it would be bug bait.  I am not sure how to improve it though.

----------
assignee: docs at python
components: Documentation
messages: 299023
nosy: docs at python, terry.reedy
priority: normal
severity: normal
stage: patch review
status: open
title: Clarify programming faq.
type: enhancement
versions: Python 3.6, Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31021>
_______________________________________