Refine events articles after review feedback

Correct wording in five events articles to reflect that AL event
subscribers bind by parameter name, not position:

- add-new-event-parameters-at-the-end: drop the inaccurate claim that
  appending a parameter forces subscribers to be updated or causes wrong
  values; keep the append-at-end best practice.
- do-not-add-ishandled-to-an-existing-event: reframe from "breaking
  change" to the semantic/purpose shift that leaves existing subscribers
  pointless; rename the breaking-change keyword to semantic-change.
- name-events-by-publisher-position: extend the good sample with
  position-named publishers raised from table and report trigger
  contexts.
- initialize-ishandled-to-false-before-publishing: scope the detection
  and best practice to events that actually carry a var IsHandled, so an
  OnBefore with no IsHandled is not flagged.
- do-not-bypass-critical-operations-with-ishandled: add a litmus-test
  definition of a critical operation (code that cannot stand as an
  independent, self-contained unit).

Knowledge-only; no contract or wiring change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-06-25 11:38:58 +02:00
parent faeacb2484
commit 0ad92cad86
5 changed files with 35 additions and 7 deletions

View file

@ -11,7 +11,7 @@ application-area: [all]
## Description
The IsHandled override pattern lets a subscriber skip the guarded code entirely. That is acceptable around a pure, side-effect-free calculation, but dangerous around critical operations — posting, ledger-entry creation, number-series consumption, and referential-integrity or permission validation. Wrapping those in `OnBeforeX(…; var IsHandled); if IsHandled then exit;` lets any subscriber silently suppress them, risking imbalanced ledgers, orphaned documents, skipped permission checks, or duplicated numbers — corruption that surfaces far from the subscriber that caused it. Make the calculation overridable, not the commit: expose the value computation through IsHandled, or offer a regular `OnAfter…` event to adjust results, while the critical work runs unconditionally.
The IsHandled override pattern lets a subscriber skip the guarded code entirely. A critical operation is one that cannot stand as an independent, self-contained unit — code whose partial execution or omission leaves the system inconsistent (imbalanced ledgers, orphaned documents, gaps in a number series, or skipped permission checks). That is acceptable around a pure, side-effect-free calculation, but dangerous around critical operations — posting, ledger-entry creation, number-series consumption, and referential-integrity or permission validation. Wrapping those in `OnBeforeX(…; var IsHandled); if IsHandled then exit;` lets any subscriber silently suppress them, risking imbalanced ledgers, orphaned documents, skipped permission checks, or duplicated numbers — corruption that surfaces far from the subscriber that caused it. Make the calculation overridable, not the commit: expose the value computation through IsHandled, or offer a regular `OnAfter…` event to adjust results, while the critical work runs unconditionally.
## Best Practice