You can open an issue on this project to raise an issue/argument about an existing rule, or to submit a new rule. For each submission, please at least produce the following items:
- Cause
- Rule description
- Justification
- How to fix violation
You can also add a code sample of the violation and a code sample with the violation fixed.
Sure! Please create an issue and we can discuss how we can work on creating multilingual versions of these guidelines.
- Be easy to follow: Each rule must be explained as simply as possible. Any developer on his/her 1st day with Xaml must be able to follow these rules,
- Be as uncontroversial as possible: These rules must be out of debate. We're not here to determine if it's better to have a white-themed Visual Studio or a black-themed one (Pro-Tip: the correct answer is of course black). So, each rule must have a justification. An inspiration from StyleCop rules can be useful,
- Be usable for any Xaml-based project: Windows Phone, WPF or Universal apps. It must apply for all of them. If a rule only applies to one platform, it should go under a platform-specific section.
Multiple attributes are declared on the same line.
A violation of this rule occurs whenever an element has multiple attributes declared on the same line. For example:
<Button x:Name="MyButton" Text="Hello world" Foreground="Blue" />Quickly, this can lead to forgotten attributes, because the XAML code editor is often split in two with code view and design view. We could apply a specific rule, like "limit to 60 column caracters" or "limit to 2 attributes per line". However, all these rules create special cases and interpretations that lead to difficulties in implementing this rule in our brain. Therefore, it's more suitable to apply a simple rule every time.
To fix a violation of this rule, place only one attribute per line.
You can also use the default key combo Ctrl+K, Ctrl+F to automatically format the current selection/document.
<Button x:Name="MyButton"
Text="Hello world"
Foreground="Blue" />When an element has at least one attribute defined, the first line contains only the element.
A violation of this rule occurs whenever an element is the only thing declared on the line.
<Button
x:Name="MyButton"
Text="Hello world"
Foreground="Blue" />Declaring only the element without one of the attributes can lead to too many carriage returns when the element contains only one attribute. We can't create an exception for these one-attribute element declarations.
Moreover, adding the attributes on subsequent lines can lead to a tab alignment which is under the element. This alignment is not optimal for reading.
Place the first attribute on the same line as the opening element.
<Button x:Name="MyButton"
Text="Hello world"
Foreground="Blue" />Within an element tag, attributes are unordered.
<Button Text="Hello world"
Foreground="Blue"
TextAlignment="Center"
/>A violation of this rule occurs whenever attributes within an element are not ordered alphabetically within the element's declaration.
Current proposal and discussions There are discussions about this rule. Please see the related proposal.
Order all attributes in alphabetical order, while complying with the related rules.
<Button Foreground="Blue"
Text="Hello world"
TextAlignment="Center"
/>- XA1004: Put the x:Name or x:Key as the first attribute
- XA1005: Put attached properties at the beginning of the element, eventually after the x:Name/x:Key
Within an element tag, with the attribute x:Name or x:Key declared, this attribute is not the first declared.
<Button Text="Hello world"
x:Name="ValidationButton"
TextAlignment="Center"
/>A violation of this rule occurs when an element declares multiple attributes and at least a x:Name or x:Key attribute, this attribute must be placed first.
These attributes are more important than any others because:
- They identify the uniqueness of a control,
- They identify that the control is used elsewere (storyboard, code behind, binding, ...).
Setting this attribute at the top helps to identify these controls and ensure any changes made to the control are done carefully.
- XA1005: Put the attached properties at the beginning of the element, eventually after the x:Name/x:Key
- XA2001: Name elements with the
x:Nameattribute
Place the x:Name or x:Key attribute first.
<Button x:Name="ValidationButton"
Text="Hello world"
TextAlignment="Center"
/>XA1005 - Put the attached properties at the beginning of the element, eventually after the x:Name/x:Key
Attached properties are declared in any order within the element properties.
<Button x:Name="ValidationButton"
Text="Hello world"
Grid.Column="2"
Grid.Row="0"
TextAlignment="Center"
/>A violation of this rule occurs when an element declares attached properties and their declaration is not at the top of all attribute declarations, except the x:Name and x:Key attributes.
Attached properties can change the appearence or behavior of your control. They can also surcharge some of the control's properties. Declaring them at the top helps you identify these cases.
Place all the attached properties, in alphabetical order, first. If x:Name and x:Key attributes are declared, they are declared before any attached property declaration.
<Button x:Name="ValidationButton"
Grid.Column="2"
Grid.Row="0"
Text="Hello world"
TextAlignment="Center"
/>An element uses a closing tag without defining child elements.
<Button x:Name="ValidationButton"
Text="Hello world"
></Button>A violation of this rule occurs when an element does not declare child tags and uses an explicit closing tag. This leads to too much space waste.
Visual Studio and Blend XAML code editors can easily expand closing tags if needed when adding the first child of an element, therefore that argument is not pertinent.
Use a self-closing element instead.
<Button x:Name="ValidationButton"
Text="Hello world"
/>Name or Key attributes are used without the namespace prefix.
<Button Name="ValidationButton"
Text="Hello world"
/>A violation of this rule occurs when the Name or Key attributes are declared without the x: namespace prefix.
These attributes are more important than any others because:
- They identify the uniqueness of a control,
- They identify that the control is used elsewere (storyboard, code behind, binding, ...).
Making this attribute more visible with the namespace prefix helps to identify these controls and ensure any changes made to them are done carefully.
Always declare x:Name or x:Key with their x: namespace prefix.
<Button x:Name="ValidationButton"
Text="Hello world"
/>This rule is under editing, waiting for comments.
An element is named without a type indication.
<Button x:Name="Checkout"
Text="Checkout"
/>A violation of this rule occurs when an element's name does not include any hint about the elment's type at the end of its name.
Suffixing an element's name helps identify the page/control class members that are part of the UI and get a sense of what we can do with them.
Suffix the element's name with a type indication.
<Button x:Name="CheckoutButton"
Text="Checkout"
/>- XA2004 Do not use a precise type indication suffix, unless it's required
An element's name indicates a precise type, however no code uses any type-specific properties/methods.
<StackPanel x:Name="ActionsStackPanel">
...
</StackPanel>ActionsStackPanel.Opacity = 0;
A violation of this rule occurs when an element's name contains precise type indication and no code is using specificities of this class, but only properties/methods defined on a base class/interface.
For a lot of use cases, you don't need to know the exact element type. Let's see it in an example:
<StackPanel x:Name="ActionsPanel">
...
</StackPanel>In this case, if you are just using ActionsPanel to change the visibility, the name is correct. ActionsStackPanel will convey too many details and prevents you from changing at a later time the StackPanel for a Grid.
However, if you will change the Orientation property somewhere, ActionsStackPanel is an appropriate name, as you should be aware that you will use specific properties of the StackPanel class.
Remove precise indication suffix.
An element defines a name and nobody uses it.
<StackPanel x:Name="ActionsPanel">
...
</StackPanel> ...
A violation of this rule occurs when an element defines a x:Name or x:Key attribute and this name/key is not referenced/used in any code-behind code, element binding, or storyboard.
Remove x:Name or x:Key attribute.
<StackPanel>
...
</StackPanel>A property value is used at least three times.
A violation of this rule occurs when a property value is used more than 2 times at different places. If so, this value will likely be used elsewhere. For greater maintenability, this property value must be declared as a resource.
- Move the value to a resource,
- Replace all value usage by a StaticResource binding.
XA3002 - All the implicit styles must be placed at the top of the file and must be annotated with a comment
An implicit style is declared elsewhere on a page/resource dictionary.
A violation of this rule occurs when an implicit style is declared anywhere on a page/resource dictionary file, except at the top.
The implicit style must be used only when they apply to a whole page/app. If they apply only to a subset of a page/app, they must be declared as explicit styles.
As these styles have a broad impact, they must be declared first and commented properly to give them visibility.
If the style is used throughout the file:
- Move the style declaration to the top of the
Resourceselement, - Add a comment before the style declaration, stating the implicit nature.
If the style is used only on a portion of the file:
- Make the style an explicit style,
- Add the proper style binding in all involved controls.
The following rules are under editing.
<!-- #Constants -->
<!-- #Colors -->
<!-- #Brushes -->
<!-- #Converters -->
<!-- #Objects (such as Data) or commands (for ribbon),etc. -->
<!-- #Styles -->
<!-- #DataTemplates -->
Please see repository contributors.
Please see open issues.
