diff --git a/sys/sys/cdefs.h b/sys/sys/cdefs.h
--- a/sys/sys/cdefs.h
+++ b/sys/sys/cdefs.h
@@ -321,6 +321,32 @@
 #define	__restrict	restrict
 #endif
 
+/*
+ * All modern compilers have explicit branch prediction so that the CPU back-end
+ * can hint the processor and also so that code blocks can be reordered such
+ * that the predicted path sees a more linear flow, thus improving cache
+ * behavior, etc.
+ *
+ * The following two macros provide us with a way to utilize this compiler
+ * feature.  Use __predict_true() if you expect the expression to evaluate to
+ * true, and __predict_false() if you expect the expression to evaluate to
+ * false.
+ *
+ * A few notes about usage:
+ *
+ *   * Generally, __predict_false() error condition checks (unless you have some
+ *     _strong_ reason to do otherwise, in which case document it), and/or
+ *     __predict_true() `no-error' condition checks, assuming you want to
+ *     optimize for the no-error case.
+ *
+ *   * Other than that, if you don't know the likelihood of a test succeeding
+ *     from empirical or other `hard' evidence, don't make predictions.
+ *
+ *   * These are meant to be used in places that are run `a lot'.  It is
+ *     wasteful to make predictions in code that is run seldomly (e.g. at
+ *     subsystem initialization time) as the basic block reordering that this
+ *     affects can often generate larger code.
+ */
 #define	__predict_true(exp)     __builtin_expect((exp), 1)
 #define	__predict_false(exp)    __builtin_expect((exp), 0)