diff --git a/microsoft/knowledge/style/caption-required-on-page-fields.bad.al b/microsoft/knowledge/style/caption-required-on-page-fields.bad.al index a31793b..21dccb3 100644 --- a/microsoft/knowledge/style/caption-required-on-page-fields.bad.al +++ b/microsoft/knowledge/style/caption-required-on-page-fields.bad.al @@ -19,7 +19,7 @@ page 50253 "Sample Caption Bad" { ApplicationArea = All; Caption = ''; - ToolTip = 'Specifies the customer name.'; + ToolTip = 'Specifies the customer name shown on sales documents.'; } } } diff --git a/microsoft/knowledge/style/caption-required-on-page-fields.good.al b/microsoft/knowledge/style/caption-required-on-page-fields.good.al index 5e8f518..f91ed73 100644 --- a/microsoft/knowledge/style/caption-required-on-page-fields.good.al +++ b/microsoft/knowledge/style/caption-required-on-page-fields.good.al @@ -9,12 +9,12 @@ table 50252 "Sample Caption Source" field(1; "No."; Code[20]) { Caption = 'No.'; - ToolTip = 'Specifies the customer number.'; + ToolTip = 'Specifies the unique number used to distinguish this customer record from other records.'; } field(2; Name; Text[100]) { Caption = 'Name'; - ToolTip = 'Specifies the customer name.'; + ToolTip = 'Specifies the name used to identify the customer alongside the unique customer number.'; } } @@ -52,7 +52,7 @@ page 50252 "Sample Caption Good" { ApplicationArea = All; Caption = 'Display Value'; - ToolTip = 'Specifies the value to display.'; + ToolTip = 'Specifies temporary text for this page; the text is not saved in the customer record.'; } } } diff --git a/microsoft/knowledge/style/caption-required-on-page-fields.md b/microsoft/knowledge/style/caption-required-on-page-fields.md index f930562..b5d2e03 100644 --- a/microsoft/knowledge/style/caption-required-on-page-fields.md +++ b/microsoft/knowledge/style/caption-required-on-page-fields.md @@ -13,6 +13,8 @@ application-area: [all] A page field bound to a table field inherits the source field's `Caption` unless the page overrides it. An inherited caption is valid, user-facing, and translatable; omitting a page-level `Caption` does not mean the control displays an internal identifier or loses translations. CodeCop AA0225/AA0226 concern missing or empty captions, not a requirement to duplicate a caption already supplied by the source table field. +Redundant page-level captions compile successfully, so compiler-error recovery does not prevent an agent from adding them. This guidance prevents that false positive rather than replacing analyzer diagnostics. + Controls bound to variables or expressions cannot rely on table-field caption inheritance. For user-facing fields that need a label, supply a `Caption` or a `CaptionClass` that resolves to the intended caption. API pages are not human-facing UI; do not apply this UI-label guidance to their API contract names. ## Best Practice diff --git a/microsoft/knowledge/style/tooltip-required-on-page-fields.good.al b/microsoft/knowledge/style/tooltip-required-on-page-fields.good.al index 26586f3..cd1fc8c 100644 --- a/microsoft/knowledge/style/tooltip-required-on-page-fields.good.al +++ b/microsoft/knowledge/style/tooltip-required-on-page-fields.good.al @@ -9,12 +9,12 @@ table 50250 "Sample Tooltip Source" field(1; "No."; Code[20]) { Caption = 'No.'; - ToolTip = 'Specifies the number that identifies the entry.'; + ToolTip = 'Specifies the unique number used to distinguish this entry from other entries.'; } field(2; Amount; Decimal) { Caption = 'Amount'; - ToolTip = 'Specifies the entry amount.'; + ToolTip = 'Specifies the monetary value recorded for this entry; changing it updates the saved entry.'; } } @@ -45,13 +45,13 @@ page 50250 "Sample Tooltip Good" field(Amount; Rec.Amount) { ApplicationArea = All; - ToolTip = 'Specifies the entry amount to use in the preview.'; + ToolTip = 'Specifies the recorded amount to compare with the temporary preview amount.'; } field(PreviewAmount; PreviewAmount) { ApplicationArea = All; Caption = 'Preview Amount'; - ToolTip = 'Specifies the amount to preview before saving.'; + ToolTip = 'Specifies a temporary amount to compare with the recorded entry amount; this value is not saved.'; } } } diff --git a/microsoft/knowledge/style/tooltip-required-on-page-fields.md b/microsoft/knowledge/style/tooltip-required-on-page-fields.md index 259399d..bd1dd2b 100644 --- a/microsoft/knowledge/style/tooltip-required-on-page-fields.md +++ b/microsoft/knowledge/style/tooltip-required-on-page-fields.md @@ -21,6 +21,8 @@ AA0218's severity is configured per app and may be downgraded or disabled. Revie On runtime 13.0 or later, define shared tooltip text on the table field and omit duplicate page-level properties. Add a page-level `ToolTip` when no tooltip can be inherited or when the page needs different, context-specific help. Describe what the value shows, conventionally starting with "Specifies" or another clear phrasing. +Make the text answer a question the caption does not: what the value is used for, which values or units are expected, or what changing it affects. Do not mechanically generate "Specifies the ." and consider the help complete. Use behavior established by the implementation or requirements; do not invent effects, defaults, or constraints to make a tooltip sound useful. Keep shared table-field help applicable to all pages that inherit it, and improve that shared text rather than duplicating it on each page. + Before raising a `medium`-severity finding, check the target runtime, the control's binding, and the source field's tooltip, including dependency symbols when needed. Report a field with neither an explicit nor an inherited tooltip independently of whether AA0218 is active. If the source definition or target runtime is unavailable, do not assume a missing page property means missing tooltip text. See sample: `tooltip-required-on-page-fields.good.al` (BC24/runtime 13.0 or later). @@ -31,8 +33,12 @@ A user-facing control with no page-level `ToolTip` and no non-empty source toolt Flagging a bound field that already inherits its tooltip, or adding the same tooltip to every page, is also incorrect: duplicate overrides add maintenance and translation work and prevent source-field tooltip changes from reaching those pages. +Treating a non-empty tooltip that merely repeats the caption as useful help is a separate quality issue, not a missing-tooltip finding. Point out the concrete information users need rather than demanding longer wording or a page-level override for its own sake. + See sample: `tooltip-required-on-page-fields.bad.al`. ## References [ToolTip property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-tooltip-property). + +[Guidelines for tooltip text](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/user-assistance#guidelines-for-tooltip-text).