Forslag: variable-names-must-be-semantically-descriptive

custom/knowledge/style/variable-names-must-be-semantically-descriptive.md

@@ -0,0 +1,65 @@
+---
+bc-version: [all]
+domain: style
+keywords: [variable-naming, semantic-naming, readability, magic-name, self-documenting]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Variable names must describe what the value means, not just its type
+
+## Description
+
+A variable name must let a reader understand what the value represents
+without having to trace every place it is assigned or used. A name built
+from a generic type abbreviation plus a sequence number or letter —
+`Amt1`, `Amt2`, `Var1`, `OptA`, `Int3`, `TempX` — fails this test: it tells
+the reader the data type, which AL already shows via the declaration, but
+nothing about the business meaning. `AmountInclVAT` is immediately
+readable; `Amt1` requires the reader to go find out what Amt1 is actually
+used for.
+
+The fix is not "add more letters" — it is to name the variable for the
+business concept it holds: `AmountInclVAT`, `CustomerDiscountPct`,
+`RemainingQuantity`, `IsOverdue`. If two variables genuinely hold the same
+kind of value in a comparison or calculation (e.g. two amounts being
+subtracted), name them for their distinct roles in that calculation
+(`OriginalAmount` / `AdjustedAmount`), not for their shared type
+(`Amt1` / `Amt2`).
+
+**Exception:** short-lived loop counters and array indices (`i`, `idx`,
+`x`) are an accepted convention precisely because their entire meaning is
+visible in the two or three lines of the loop that declares and uses them.
+This exception does not extend to variables that live longer than a tight
+loop body or that carry business meaning beyond "the current position."
+
+## Best Practice
+
+```al
+var
+    AmountInclVAT: Decimal;
+    RemainingQuantity: Decimal;
+    IsOverdue: Boolean;
+...
+for idx := 1 to ArrayLen(SalesLine) do
+    TotalAmount += SalesLine[idx];
+```
+
+## Anti Pattern
+
+```al
+var
+    Amt1: Decimal;
+    Amt2: Decimal;
+    OptA: Option;
+    TempX: Integer;
+...
+if OptA = 1 then
+    Amt1 := Amt2 - TempX;
+```
+
+A reviewer reading `Amt1 := Amt2 - TempX;` cannot tell what this line is
+computing without opening the variable declarations and searching for every
+other assignment to `Amt2` and `TempX` first. The same line as
+`AmountInclVAT := AmountExclVAT - DiscountAmount;` needs no further lookup.