diff --git a/docs/nix.md b/docs/nix.md index 393169f..995deab 100644 --- a/docs/nix.md +++ b/docs/nix.md @@ -131,10 +131,10 @@ Use: ## `let` Bindings -### Name the role, not the type +### Use role-specific binding names -Use a `let` binding when the name explains the value's role. -Do not introduce a vague name only to shorten an expression. +A `let` binding name must explain the value's role in the expression. +Avoid names that describe only the value's type. Avoid: @@ -154,10 +154,9 @@ in lib.genAttrs hostNames mkHost ``` -### Share important repeated values +### Bind shared expressions once -Use a `let` binding when multiple expressions share one important value. -Do not repeat an expression when repetition makes the relationship less clear. +Use a `let` binding when sibling expressions depend on the same derived value. Avoid: @@ -180,10 +179,9 @@ in } ``` -### Keep bindings near their use +### Keep bindings in the smallest scope -Place a `let` binding in the smallest expression that needs it. -Do not lift a value to a larger scope only for convenience. +Place a `let` binding inside the expression that consumes it. Avoid: @@ -192,7 +190,10 @@ let hostNames = lib.attrNames hosts; in { - hostCount = lib.length hostNames; + hostSummary = { + inherit hostNames; + count = lib.length hostNames; + }; nixosConfigurations = flakeAssembly.mkHosts (self + "/hosts"); } ``` @@ -201,7 +202,14 @@ Use: ```nix { - hostCount = lib.length (lib.attrNames hosts); + hostSummary = + let + hostNames = lib.attrNames hosts; + in + { + inherit hostNames; + count = lib.length hostNames; + }; nixosConfigurations = flakeAssembly.mkHosts (self + "/hosts"); } ```