From c06effd01e209e17a0cd4c6bea36357ce2859d8d Mon Sep 17 00:00:00 2001
From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com>
Date: Wed, 12 Aug 2026 22:30:50 +0200
Subject: [PATCH 1/2] Forslag: variable-names-must-be-semantically-descriptive

---
 ...-names-must-be-semantically-descriptive.md | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 custom/knowledge/style/variable-names-must-be-semantically-descriptive.md

diff --git a/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md b/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md
new file mode 100644
index 0000000..397164d
--- /dev/null
+++ b/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.

From 35c29f6af358dfb19ff88c58435ed90e860cf72d Mon Sep 17 00:00:00 2001
From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com>
Date: Wed, 12 Aug 2026 22:37:28 +0200
Subject: [PATCH 2/2] Udvid undtagelse: s/c i Dialog/Window progress-idiom er
 ogsaa accepteret

---
 ...-names-must-be-semantically-descriptive.md | 25 +++++++++++++++----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md b/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md
index 397164d..c86f349 100644
--- a/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md
+++ b/custom/knowledge/style/variable-names-must-be-semantically-descriptive.md
@@ -28,11 +28,19 @@ 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."
+**Exception:** short-lived variables in a handful of idiomatic, universally
+recognized roles are accepted single-letter, because their entire meaning
+is visible in the few lines that declare and use them:
+- Loop counters and array indices (`i`, `idx`, `x`).
+- The progress step counter in a `Dialog`/progress-window idiom — a status
+  iterator whose only job is tracking how far a long-running process has
+  gotten (`s`), and the count fed into the update call itself, e.g.
+  `Window.Update(1, c)` (`c`).
+
+This exception does not extend to variables that live longer than that
+tight idiomatic scope, or that carry business meaning beyond "the current
+position" or "the current progress count" — a `Status` field on a table, or
+a `Counter` that is read elsewhere in the object, still needs a real name.
 
 ## Best Practice
 
@@ -44,6 +52,13 @@ var
 ...
 for idx := 1 to ArrayLen(SalesLine) do
     TotalAmount += SalesLine[idx];
+...
+Window.Open('Processing #1#########');
+for s := 1 to Item.Count do begin
+    c += 1;
+    Window.Update(1, Round(c / Item.Count * 10000, 1));
+end;
+Window.Close();
 ```
 
 ## Anti Pattern