guidelines-and-best-practices-eaeea19.md

Guidelines and Best Practices

There are some general guidelines for writing succinct and meaningful rules to ensure high quality, consistency and better usability of the reported issues.

Rule Property Values

The following table contains guidelines and examples on how to set the rule property values.

Field	Guidelines / Explanation	Example / Clarification
ID	CamelCase Start with small caps	hardcodedTextValues
Async	Defines if the rule check function will contain asynchronous operations. It can be true or false. The default value is false.	Make sure you use the resolve function in your rule check function as a 4th parameter.
Audiences	Control - rule is relevant for control developers Internal - rule is relevant for an SAP internal developer Application - rule is relevant for app developers	Choose one.
Categories	A list of categories checked that show which aspects of the application are affected by the rule. Examples: Performance Model Bindings Memory	Choose one or more, or add your own.
Min version	The minimum OpenUI5 version required so that the rule can produce valid results. The Support Assistant considers applicable rules according to their minversion value. If you have rules in your custom library, keep in mind that the rule minversion will still be compared against the underlying OpenUI5 version. If you are not aware of the version, you can put in the minversion field "*", "-" or whitespace (" ") to make sure these rules are executed.	for example, 1.44 for OpenUI5 version comparison or "*", "-", or whitespace (" ") to avoid version filtering.
Max version	The maximum OpenUI5 version required to run the rule.	(currently not taken into account)
Title	As short as possible, as descriptive as possible. (Where applicable) - <Control Name (no namespace)>: Description of issue Sentence case.	Page: invalid background design property
Description	Briefly explain what the rule does/checks. Ideally one sentence. No period. Avoid explaining how to fix the issue.	Dialogs with content should have ariaLabelledBy association set
Resolution	Explain how to fix the issue. Use imperative. Ideally one sentence. No period. Could be left out if it is trivial and already explained in the Description.	Set property upperCase to false or add icons to IconTabFilters
Details	Contains technical details on a rule that was triggered for a specific element. References specific errors and should not be a resolution hint.	Element{0} has no icon but its parent Element{1} has property upperCase set to true.
URLs	Ideally every rule should point to a topic or document in the DevGuide, API Reference, Samples, or SAP Fiori Design Guidelines. Use the following text values when referring to specific parts of the documentation: Developer Guide - Documentation: <Title of topic> API Reference - API Reference: <Name of control + path to method/property> SAP Fiori Guidelines - SAP Fiori Guidelines: <Name of control> External Link - no description text, just a URL	Documentation: Element Binding API Reference: ComboBox #getSelectedItem SAP Fiori Design Guidelines: RadioButton
Check function	Check function code	function (issueManager, oCoreFacade, oScope) { ... }

Check Function Guidelines

Here are some general guidelines that you should consider when creating a new rule:

• Create very specific rules

  It is important that the rules are as specific as possible. Avoid too generic or unspecific rules that would produce excessive number of issues difficult to digest or follow up. The rules should focus on one issue and provide a resolution for it.

• Reduce the number of issues generated

  Do not overload the user with a large number of issues. When appropriate, produce one issue where multiple texts are concatenated with \n delimiter.

• Write clear descriptions and resolutions

  Use the guidelines in Create a Ruleset for a Library