From 276e4a3172c883dfe6327e0a472b511991eca53f Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Fri, 28 Aug 2026 10:14:50 -0400
Subject: [PATCH] docs(nix): split let binding rules

---
 docs/nix.md | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/docs/nix.md b/docs/nix.md
index 67b6408..393169f 100644
--- a/docs/nix.md
+++ b/docs/nix.md
@@ -131,11 +131,10 @@ Use:
 
 ## `let` Bindings
 
-### Use `let` to name concepts
+### Name the role, not the type
 
 Use a `let` binding when the name explains the value's role.
-Use a `let` binding when multiple expressions share one important value.
-Do not use a `let` binding only to shorten a function call.
+Do not introduce a vague name only to shorten an expression.
 
 Avoid:
 
@@ -155,11 +154,36 @@ in
 lib.genAttrs hostNames mkHost
 ```
 
-### Keep `let` bindings near their use
+### Share important repeated values
+
+Use a `let` binding when multiple expressions share one important value.
+Do not repeat an expression when repetition makes the relationship less clear.
+
+Avoid:
+
+```nix
+{
+  hostNames = lib.attrNames hosts;
+  hostCount = lib.length (lib.attrNames hosts);
+}
+```
+
+Use:
+
+```nix
+let
+  hostNames = lib.attrNames hosts;
+in
+{
+  inherit hostNames;
+  hostCount = lib.length hostNames;
+}
+```
+
+### Keep bindings near their use
 
 Place a `let` binding in the smallest expression that needs it.
 Do not lift a value to a larger scope only for convenience.
-A larger scope makes the dependency look more important than it is.
 
 Avoid: