classification
Title: Awkward phrasing in Decimal documentation
Type: Stage:
Components: Documentation Versions: Python 3.3
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, rhettinger, zacherates
Priority: low Keywords: patch

Created on 2012-01-07 19:16 by zacherates, last changed 2012-01-07 22:48 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
rephrase.diff zacherates, 2012-01-07 19:16 review
Messages (6)
msg150814 - (view) Author: Aaron Maenpaa (zacherates) Date: 2012-01-07 19:16
The paragraph: "The exactness carries over into arithmetic. In decimal floating point, 0.1 + 0.1 + 0.1 - 0.3 is exactly equal to zero. In binary floating point, the result is 5.5511151231257827e-017. While near to zero, the differences prevent reliable equality testing and differences can accumulate. For this reason, decimal is preferred in accounting applications which have strict equality invariants."

... has some awkward phrasing to my ear. I've attached a patch with a proposed alternative.
msg150819 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-01-07 21:12
I'm sorry but I think the current wording is better that your proposed revision.

When I get a chance, I'll revisit it to see if I can find another way to improve the text.
msg150823 - (view) Author: Aaron Maenpaa (zacherates) Date: 2012-01-07 21:39
That's fine. I'm not particularly attached to that phrasing.

The one thing I would push for is to add a comma to "... decimal is preferred in accounting applications which have strict equality invariants."

... since, as far as I can tell, "which have strict equality invariants" is supposed to be a parenthetical statement explaining why accounting applications prefer to use decimal arithmetic, rather than a constraints on the preference for decimal arithmetic to only those accounting applications that have "strict equality invariants".
msg150825 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-01-07 22:42
If you can't ascertain the meaning of the sentence, I'll consider making a change.  Itherwise, this appears to have degenerated into trivial micro-wordsmithing and I'll close this as not being worth consuming any more of my time.
msg150826 - (view) Author: Aaron Maenpaa (zacherates) Date: 2012-01-07 22:47
I can understand what was meant. You're welcome to close the issue.

Sorry for the nitpick.
msg150827 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2012-01-07 22:48
No problem.  Thanks for showing an interest in the quality of the documentation.
History
Date User Action Args
2012-01-07 22:48:26rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg150827
2012-01-07 22:47:33zacheratessetmessages: + msg150826
2012-01-07 22:42:38rhettingersetmessages: + msg150825
2012-01-07 21:39:12zacheratessetmessages: + msg150823
2012-01-07 21:12:22rhettingersetpriority: normal -> low

messages: + msg150819
2012-01-07 21:08:37rhettingersetassignee: docs@python -> rhettinger

nosy: + rhettinger
2012-01-07 19:16:46zacheratescreate