Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 06:36:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/events/reset-ishandled-only-when-the-value-can-carry-over.md
wenjiefan 5016962b40 Align the IsHandled article slug, keywords and good sample with its narrowed scope 
The article was rewritten to say a reset is required only when the value can
carry over, and its H1 was updated to match, but three artefacts still carried
the old "always initialize to false" premise:

- The slug still read `initialize-ishandled-to-false-before-publishing`, which
  contradicts the body. The slug is not cosmetic: Build-KnowledgeIndex.ps1
  ranks candidates on keywords, frontmatter dimensions, domain, path and title,
  so a stale path pushes selection back toward the behaviour this change
  narrows. Renamed to `reset-ishandled-only-when-the-value-can-carry-over`,
  following the existing precedent for conditional slugs such as
  `unreleased-symbol-change-is-not-a-breaking-change`.
- Keywords still listed `initialization` and `deterministic` and omitted
  `false-positive`, the tag this repository uses for suppression articles.
  Replaced with `carry-over` and `loop-iteration` and added `false-positive`.
- The good sample demonstrated only the "prefer separate fresh locals" clause
  and contained no reset at all, so the article's headline case had no positive
  example. It was also asymmetric with the bad sample, which gained a loop
  procedure showing a local that carries `true` into the next iteration.

Added the matching loop procedure to the good sample: a local declared outside
the loop is reset at the top of each iteration. That case cannot be solved by
introducing another local, because AL has no block scope, so it is the only
shape that demonstrates the reset the article still requires. It also gives the
engine the correct `suggested-code` shape for the loop finding; without it the
one-click fix adapted from the good sample would propose splitting the variable
rather than adding one line.

Also renamed the sample codeunits from "IsHandled Init ..." to
"IsHandled Carry Over ...", and updated the two references to the old slug:
the events leaf skill cue and the events pin in evaluation/review-fixtures.json.

validate_frontmatter.py reports 0 errors; Test-ReviewFixtures.ps1 passes with
32 cases across 16 leaf domains and resolves the events fixture to the renamed
article.
2026-09-02 11:08:16 +02:00

2.3 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
events
ishandled
carry-over
loop-iteration
onbefore
reset
integration-event
control-flow
false-positive
al
w1
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, 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.