1 files changed, 7 insertions, 0 deletions

diff --git a/docs/dev/style.md b/docs/dev/style.md
index d24a5952e..9b0ddec66 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -636,6 +636,10 @@ use crate::{}
 
 // Finally, parent and child modules, but prefer `use crate::`.
 use super::{}
+
+// Re-exports are treated as item definitions rather than imports, so they go
+// after imports and modules. Use them sparingly.
+pub use crate::x::Z;
 ```
 
 **Rationale:** consistency.
@@ -694,6 +698,9 @@ Avoid local `use MyEnum::*` imports.
 Prefer `use crate::foo::bar` to `use super::bar` or `use self::bar::baz`.
 **Rationale:** consistency, this is the style which works in all cases.
 
+By default, avoid re-exports.
+**Rationale:** for non-library code, re-exports introduce two ways to use something and allow for inconsistency.
+
 ## Order of Items
 
 Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.