summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTaylor Yu <catalyst@torproject.org>2017-09-07 17:38:25 -0500
committerTaylor Yu <catalyst@torproject.org>2017-09-08 12:15:41 -0500
commit55fef0534d86fc276186ff0f7c1c8f95531c57c9 (patch)
tree9faf564be19799a64cb8706b2f1fb06d7633fc24 /doc
parente5e2df36f3cad69a63b46ed589f250afb31ab476 (diff)
downloadtor-55fef0534d86fc276186ff0f7c1c8f95531c57c9.tar.gz
tor-55fef0534d86fc276186ff0f7c1c8f95531c57c9.zip
Add guidelines for floating point use
Diffstat (limited to 'doc')
-rw-r--r--doc/HACKING/CodingStandards.md60
1 files changed, 60 insertions, 0 deletions
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index a8fca4a770..1012a4c9c9 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -178,6 +178,66 @@ We don't call `memcmp()` directly. Use `fast_memeq()`, `fast_memneq()`,
Also see a longer list of functions to avoid in:
https://people.torproject.org/~nickm/tor-auto/internal/this-not-that.html
+Floating point math is hard
+---------------------------
+
+Floating point arithmetic as typically implemented by computers is
+very counterintuitive. Failure to adequately analyze floating point
+usage can result in surprising behavior and even security
+vulnerabilities!
+
+General advice:
+
+ - Don't use floating point.
+ - If you must use floating point, document how the limits of
+ floating point precision and calculation accuracy affect function
+ outputs.
+ - Try to do as much as possible of your calculations using integers
+ (possibly acting as fixed-point numbers) and convert to floating
+ point for display.
+ - If you must send floating point numbers on the wire, serialize
+ them in a platform-independent way. Tor avoids exchanging
+ floating-point values, but when it does, it uses ASCII numerals,
+ with a decimal point (".").
+ - Binary fractions behave very differently from decimal fractions.
+ Make sure you understand how these differences affect your
+ calculations.
+ - Every floating point arithmetic operation is an opportunity to
+ lose precision, overflow, underflow, or otherwise produce
+ undesired results. Addition and subtraction tend to be worse
+ than multiplication and division (due to things like catastrophic
+ cancellation). Try to arrange your calculations to minimize such
+ effects.
+ - Changing the order of operations changes the results of many
+ floating-point calculations. Be careful when you simplify
+ calculations! If the order is significant, document it using a
+ code comment.
+ - Comparing most floating point values for equality is unreliable.
+ Avoid using `==`, instead, use `>=` or `<=`. If you use an
+ epsilon value, make sure it's appropriate for the ranges in
+ question.
+ - Different environments (including compiler flags and per-thread
+ state on a single platform!) can get different results from the
+ same floating point calculations. This means you can't use
+ floats in anything that needs to be deterministic, like consensus
+ generation. This also makes reliable unit tests of
+ floating-point outputs hard to write.
+
+For additional useful advice (and a little bit of background), see
+[What Every Programmer Should Know About Floating-Point
+Arithmetic](http://floating-point-gui.de/).
+
+A list of notable (and surprising) facts about floating point
+arithmetic is at [Floating-point
+complexities](https://randomascii.wordpress.com/2012/04/05/floating-point-complexities/).
+Most of that [series of posts on floating
+point](https://randomascii.wordpress.com/category/floating-point/) is
+helpful.
+
+For more detailed (and math-intensive) background, see [What Every
+Computer Scientist Should Know About Floating-Point
+Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html).
+
Other C conventions
-------------------