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

Address tooltip quality and knowledge scope review feedback

Browse source 
Require useful, behavior-grounded tooltip text rather than caption repetition, improve the samples, and explain why compiler feedback does not prevent redundant page captions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-09-07 15:10:15 +02:00
parent db767a0336
commit 11aefa9125
5 changed files with 16 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

2
microsoft/knowledge/style/caption-required-on-page-fields.bad.al
View file

@ -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.';
}
}
}

6
microsoft/knowledge/style/caption-required-on-page-fields.good.al
View file

@ -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.';
}
}
}

2
microsoft/knowledge/style/caption-required-on-page-fields.md
View file

@ -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

8
microsoft/knowledge/style/tooltip-required-on-page-fields.good.al
View file

@ -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.';
}
}
}

6
microsoft/knowledge/style/tooltip-required-on-page-fields.md
View file

@ -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 <field name>." 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).