Merge pull request #132 from microsoft/gggdttt-refine-self-improvement-guidance

Refine self-improvement review guidance

microsoft/knowledge/events/initialize-ishandled-to-false-before-publishing.bad.al

@@ -1,31 +0,0 @@
-// Demonstration-only AL. Not compiled by CI; illustrates the article.
-codeunit 50241 "IsHandled Init Bad Sample"
-{
-    procedure ApplyDiscounts(var SalesHeader: Record "Sales Header")
-    var
-        DiscountPct: Decimal;
-        IsHandled: Boolean;
-    begin
-        // IsHandled is never initialized before the first raise, so flow depends
-        // on the variable's default rather than an explicit, documented intent.
-        OnBeforeApplyHeaderDiscount(SalesHeader, DiscountPct, IsHandled);
-        if not IsHandled then
-            DiscountPct := 5;
-
-        // Bug: IsHandled is not reset. If the first subscriber set it true, the
-        // payment-discount default below is silently skipped too.
-        OnBeforeApplyPaymentDiscount(SalesHeader, DiscountPct, IsHandled);
-        if not IsHandled then
-            DiscountPct += 2;
-    end;
-
-    [IntegrationEvent(false, false)]
-    local procedure OnBeforeApplyHeaderDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
-    begin
-    end;
-
-    [IntegrationEvent(false, false)]
-    local procedure OnBeforeApplyPaymentDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
-    begin
-    end;
-}

microsoft/knowledge/events/initialize-ishandled-to-false-before-publishing.good.al

@@ -1,31 +0,0 @@
-// Demonstration-only AL. Not compiled by CI; illustrates the article.
-codeunit 50240 "IsHandled Init Good Sample"
-{
-    procedure ApplyDiscounts(var SalesHeader: Record "Sales Header")
-    var
-        DiscountPct: Decimal;
-        IsHandled: Boolean;
-    begin
-        IsHandled := false;
-        OnBeforeApplyHeaderDiscount(SalesHeader, DiscountPct, IsHandled);
-        if not IsHandled then
-            DiscountPct := 5;
-
-        // Reset before reusing the same variable for the next event so a
-        // subscriber that handled the first raise can't suppress this one.
-        IsHandled := false;
-        OnBeforeApplyPaymentDiscount(SalesHeader, DiscountPct, IsHandled);
-        if not IsHandled then
-            DiscountPct += 2;
-    end;
-
-    [IntegrationEvent(false, false)]
-    local procedure OnBeforeApplyHeaderDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
-    begin
-    end;
-
-    [IntegrationEvent(false, false)]
-    local procedure OnBeforeApplyPaymentDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
-    begin
-    end;
-}

microsoft/knowledge/events/initialize-ishandled-to-false-before-publishing.md

@@ -1,26 +0,0 @@
----
-bc-version: [all]
-domain: events
-keywords: [ishandled, initialization, deterministic, onbefore, reset, integration-event, control-flow]
-technologies: [al]
-countries: [w1]
-application-area: [all]
----
-
-# Initialize IsHandled to false before publishing
-
-## Description
-
-A routine that raises an `OnBefore…` integration event with a `var IsHandled: Boolean` parameter passes that variable in by reference, so its incoming value decides whether the default logic is skipped. A freshly declared Boolean starts as `false`, but the same variable is frequently reused to raise several events in one routine, and after the first raise it may already be `true`. Assigning `IsHandled := false;` on the line immediately before every raise makes the control flow deterministic and self-documenting, and prevents a stale `true` from silently suppressing logic the author never meant to make skippable. Generated code often reuses one `IsHandled` across several raises without resetting it.
-
-## Best Practice
-
-Set `IsHandled := false;` immediately before each `OnBeforeX(…, IsHandled)` raise, then guard the default logic with `if IsHandled then exit;` or `if not IsHandled then …`. Do this even when the variable was just declared: the explicit reset documents intent and stays correct if a second event raise is added to the routine later. This applies only to events that carry a `var IsHandled: Boolean`; an `OnBefore` event with no `IsHandled` parameter needs no reset.
-
-See sample: `initialize-ishandled-to-false-before-publishing.good.al`.
-
-## Anti Pattern
-
-Raising `OnBeforeX(…, IsHandled)` with a variable whose value carries over from an earlier raise, so a subscriber that handled the first event unintentionally suppresses the second routine's default logic. Detection: an `IsHandled` variable passed to more than one event in a routine without an intervening `IsHandled := false;`, or any `OnBefore…` raise that passes an `IsHandled` variable without an intervening `IsHandled := false;`.
-
-See sample: `initialize-ishandled-to-false-before-publishing.bad.al`.

microsoft/knowledge/events/reset-ishandled-only-when-the-value-can-carry-over.bad.al

@@ -0,0 +1,48 @@
+// Demonstration-only AL. Not compiled by CI; illustrates the article.
+codeunit 50241 "IsHandled Carry Over Bad Sample"
+{
+    procedure ApplyDiscounts(var SalesHeader: Record "Sales Header")
+    var
+        DiscountPct: Decimal;
+        IsHandled: Boolean;
+    begin
+        OnBeforeApplyHeaderDiscount(SalesHeader, DiscountPct, IsHandled);
+        if not IsHandled then
+            DiscountPct := 5;
+
+        // Bug: execution continues when the first event set IsHandled to true,
+        // and that stale value is passed to a different publisher.
+        OnBeforeApplyPaymentDiscount(SalesHeader, DiscountPct, IsHandled);
+        if not IsHandled then
+            DiscountPct += 2;
+    end;
+
+    procedure ApplyLineDiscounts(var SalesLine: Record "Sales Line")
+    var
+        LineIsHandled: Boolean;
+    begin
+        if SalesLine.FindSet() then
+            repeat
+                // Bug: the local initializes only once. A subscriber that handles
+                // one line leaves true for every later iteration.
+                OnBeforeApplyLineDiscount(SalesLine, LineIsHandled);
+                if not LineIsHandled then
+                    SalesLine.Validate("Line Discount %", 5);
+            until SalesLine.Next() = 0;
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyHeaderDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
+    begin
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyPaymentDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
+    begin
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyLineDiscount(var SalesLine: Record "Sales Line"; var IsHandled: Boolean)
+    begin
+    end;
+}

microsoft/knowledge/events/reset-ishandled-only-when-the-value-can-carry-over.good.al

@@ -0,0 +1,50 @@
+// Demonstration-only AL. Not compiled by CI; illustrates the article.
+codeunit 50240 "IsHandled Carry Over Good Sample"
+{
+    procedure ApplyDiscounts(var SalesHeader: Record "Sales Header")
+    var
+        DiscountPct: Decimal;
+        HeaderIsHandled: Boolean;
+        PaymentIsHandled: Boolean;
+    begin
+        // Each fresh local is false and belongs to one non-looping raise.
+        OnBeforeApplyHeaderDiscount(SalesHeader, DiscountPct, HeaderIsHandled);
+        if not HeaderIsHandled then
+            DiscountPct := 5;
+
+        // Handling the header event does not suppress this independent seam.
+        OnBeforeApplyPaymentDiscount(SalesHeader, DiscountPct, PaymentIsHandled);
+        if not PaymentIsHandled then
+            DiscountPct += 2;
+    end;
+
+    procedure ApplyLineDiscounts(var SalesLine: Record "Sales Line")
+    var
+        LineIsHandled: Boolean;
+    begin
+        if SalesLine.FindSet() then
+            repeat
+                // The local initializes once, so reset it per iteration; a
+                // subscriber that handles one line must not skip the rest.
+                LineIsHandled := false;
+                OnBeforeApplyLineDiscount(SalesLine, LineIsHandled);
+                if not LineIsHandled then
+                    SalesLine.Validate("Line Discount %", 5);
+            until SalesLine.Next() = 0;
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyHeaderDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
+    begin
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyPaymentDiscount(var SalesHeader: Record "Sales Header"; var DiscountPct: Decimal; var IsHandled: Boolean)
+    begin
+    end;
+
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeApplyLineDiscount(var SalesLine: Record "Sales Line"; var IsHandled: Boolean)
+    begin
+    end;
+}

microsoft/knowledge/events/reset-ishandled-only-when-the-value-can-carry-over.md

@@ -0,0 +1,26 @@
+---
+bc-version: [all]
+domain: events
+keywords: [ishandled, carry-over, loop-iteration, onbefore, reset, integration-event, control-flow, false-positive]
+technologies: [al]
+countries: [w1]
+application-area: [all]
+---
+
+# Reset IsHandled before publishing only when its value can carry over
+
+## Description
+
+A routine that raises an `OnBefore…` integration event with a `var IsHandled: Boolean` parameter passes that variable by reference, so a pre-existing `true` can affect the following control flow. AL [automatically initializes Boolean variables to `false`](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-al-variables#initialization), so a freshly declared local Boolean passed to one event exactly once per procedure invocation is already deterministic. Initialization does not repeat for each loop iteration: a local declared outside a loop can carry `true` from one iteration to the next even when the source contains only one textual event raise. Outside a loop, reaching a later raise after `if IsHandled then exit;` also proves the value is `false`, provided that early exit is semantically correct and does not skip required downstream events.
+
+## Best Practice
+
+Reset `IsHandled := false;` before a raise only when the value might otherwise carry over as `true`: the same variable is reused after an earlier raise without a control-flow proof that it is false, a raise is re-entered by a loop, the value comes from an input parameter, field, or global, or earlier code seeds it. Prefer separate fresh locals when independent event seams need independent handled state. A reset on a guaranteed-false fresh local used by one non-looping raise, or before a later raise reached only after a semantically valid `if IsHandled then exit;`, can be retained for readability, but its absence is not a correctness finding.
+
+See sample: `reset-ishandled-only-when-the-value-can-carry-over.good.al`.
+
+## Anti Pattern
+
+Raising `OnBeforeX(…, IsHandled)` when the variable can still be `true` from an earlier raise, an earlier loop iteration, or another source, so the publisher call starts with stale state. Do not match a single non-looping raise using a fresh local Boolean, or a later raise reached only after a semantically valid `if IsHandled then exit;` proves the value is false.
+
+See sample: `reset-ishandled-only-when-the-value-can-carry-over.bad.al`.