mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-10-05 22:56:55 +01:00
65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
---
|
|
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.
|