├── LICENSE
└── README.md


/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2014 Christopher MANEU
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | XAML Coding guidelines
  2 | ======================
  3 | 
  4 | ## How to contribute
  5 | 
  6 | 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:
  7 | 
  8 | - Cause
  9 | - Rule description
 10 | - Justification
 11 | - How to fix violation
 12 | 
 13 | You can also add a code sample of the violation and a code sample with the violation fixed.
 14 | 
 15 | ### Want to translate the XAML coding guidelines in another language ?
 16 | 
 17 | Sure! Please create an issue and we can discuss how we can work on creating multilingual versions of these guidelines.
 18 | 
 19 | ## Guideline principles
 20 | 
 21 | - **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,
 22 | - **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](http://www.stylecop.com/docs/StyleCop%20Rules.html) rules can be useful,
 23 | - **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.
 24 | 
 25 | 
 26 | ## Rules
 27 | 
 28 | ### XA1x. Code readability
 29 | 
 30 | #### XA1001 - Put one attribute per line
 31 | ##### **Cause**
 32 | Multiple attributes are declared on the same line.
 33 | 
 34 | ##### **Rule description**
 35 | A violation of this rule occurs whenever an element has multiple attributes declared on the same line. For example: 
 36 | 
 37 | ```xml
 38 | <Button x:Name="MyButton" Text="Hello world" Foreground="Blue"  />
 39 | ```
 40 | 
 41 | 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.
 42 | 
 43 | ##### **How to fix violation**
 44 | To fix a violation of this rule, place only one attribute per line.
 45 | 
 46 | You can also use the default key combo `Ctrl+K, Ctrl+F` to automatically format the current selection/document.
 47 | 
 48 | ```xml
 49 | <Button x:Name="MyButton" 
 50 |         Text="Hello world" 
 51 |         Foreground="Blue"  />
 52 | ```
 53 | 
 54 | #### XA1002 - Put the first attribute on the element line
 55 | 
 56 | ##### **Cause**
 57 | When an element has at least one attribute defined, the first line contains only the element.
 58 | 
 59 | ##### **Rule description**
 60 | A violation of this rule occurs whenever an element is the only thing declared on the line.
 61 | 
 62 | ```xml
 63 | <Button 
 64 |     x:Name="MyButton" 
 65 |     Text="Hello world" 
 66 |     Foreground="Blue"  />
 67 | ```
 68 | 
 69 | 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.
 70 | 
 71 | 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.
 72 | 
 73 | ##### **How to fix violation**
 74 | Place the first attribute on the same line as the opening element.
 75 | ```xml
 76 | <Button x:Name="MyButton" 
 77 |         Text="Hello world" 
 78 |         Foreground="Blue"  />
 79 | ```
 80 | 
 81 | #### XA1003 - Within an element, order attributes alphabetically
 82 | ##### **Cause**
 83 | Within an element tag, attributes are unordered.
 84 | ```xml
 85 | <Button Text="Hello world" 
 86 |         Foreground="Blue"
 87 |         TextAlignment="Center"
 88 |         />
 89 | ```
 90 | 
 91 | ##### **Rule description**
 92 | A violation of this rule occurs whenever attributes within an element are not ordered alphabetically within the element's declaration.
 93 | 
 94 | **Current proposal and discussions**
 95 | There are discussions about this rule. Please see the [related proposal](https://github.com/cmaneu/xaml-coding-guidelines/issues/1).
 96 | 
 97 | ##### **How to fix violation**
 98 | Order all attributes in alphabetical order, while complying with the related rules.
 99 | 
100 | ```xml
101 | <Button Foreground="Blue"
102 |         Text="Hello world" 
103 |         TextAlignment="Center"
104 |         />
105 | ```
106 | 
107 | 
108 | ##### **Related rules**
109 | 
110 | - **XA1004**: Put the x:Name or x:Key as the first attribute
111 | - **XA1005**: Put attached properties at the beginning of the element, eventually after the x:Name/x:Key
112 | 
113 | #### XA1004 - Put the x:Name or x:Key as the first attribute
114 | ##### **Cause**
115 | Within an element tag, with the attribute `x:Name` or `x:Key` declared, this attribute is not the first declared.
116 | 
117 | ```xml
118 | <Button Text="Hello world" 
119 |         x:Name="ValidationButton"
120 |         TextAlignment="Center"
121 |         />
122 | ```
123 | 
124 | ##### **Rule description**
125 | 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.
126 | 
127 | These attributes are more important than any others because:
128 | - They identify the uniqueness of a control, 
129 | - They identify that the control is used elsewere (storyboard, code behind, binding, ...).
130 | 
131 | Setting this attribute at the top helps to identify these controls and ensure any changes made to the control are done carefully.
132 | 
133 | 
134 | ##### **Related rules**
135 | 
136 | - **XA1005**: Put the attached properties at the beginning of the element, eventually after the x:Name/x:Key
137 | - **XA2001**: Name elements with the `x:Name` attribute
138 | 
139 | ##### **How to fix violation**
140 | Place the `x:Name` or `x:Key` attribute first.
141 | ```xml
142 | <Button x:Name="ValidationButton"
143 |         Text="Hello world" 
144 |         TextAlignment="Center"
145 |         />
146 | ```
147 | 
148 | 
149 | 
150 | #### XA1005 - Put the attached properties at the beginning of the element, eventually after the x:Name/x:Key
151 | ##### **Cause**
152 | Attached properties are declared in any order within the element properties.
153 | 
154 | ```xml
155 | <Button x:Name="ValidationButton"
156 |         Text="Hello world" 
157 |         Grid.Column="2"
158 |         Grid.Row="0"
159 |         TextAlignment="Center"
160 |         />
161 | ```
162 | 
163 | ##### **Rule description**
164 | 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.
165 | 
166 | 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.
167 | 
168 | ##### **How to fix violation**
169 | 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.
170 | 
171 | ```xml
172 | <Button x:Name="ValidationButton"
173 |         Grid.Column="2"
174 |         Grid.Row="0"
175 |         Text="Hello world" 
176 |         TextAlignment="Center"
177 |         />
178 | ```
179 | 
180 | 
181 | #### XA1006 - If an element has no content, use a self-closing element
182 | ##### **Cause**
183 | An element uses a closing tag without defining child elements.
184 | 
185 | ```xml
186 | <Button x:Name="ValidationButton"
187 |         Text="Hello world" 
188 |         ></Button>
189 | ```
190 | 
191 | ##### **Rule description**
192 | A violation of this rule occurs when an element does not declare child tags and uses an explicit closing tag.
193 | This leads to too much space waste.
194 | 
195 | 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.
196 | 
197 | ##### **How to fix violation**
198 | Use a self-closing element instead.
199 | 
200 | ```xml
201 | <Button x:Name="ValidationButton"
202 |         Text="Hello world" 
203 |         />
204 | ```
205 | 
206 | ### XA2x. Naming
207 | 
208 | #### XA2001 - Name elements with the `x:Name` or `x:Key` attribute
209 | ##### **Cause**
210 | Name or Key attributes are used without the namespace prefix.
211 | 
212 | ```xml
213 | <Button Name="ValidationButton"
214 |         Text="Hello world" 
215 |         />
216 | ```
217 | 
218 | ##### **Rule description**
219 | A violation of this rule occurs when the `Name` or `Key` attributes are declared without the `x:` namespace prefix.
220 | 
221 | These attributes are more important than any others because:
222 | - They identify the uniqueness of a control, 
223 | - They identify that the control is used elsewere (storyboard, code behind, binding, ...).
224 | 
225 | Making this attribute more visible with the namespace prefix helps to identify these controls and ensure any changes made to them are done carefully.
226 | 
227 | ##### **How to fix violation**
228 | Always declare `x:Name` or `x:Key` with their `x:` namespace prefix.
229 | 
230 | ```xml
231 | <Button x:Name="ValidationButton"
232 |         Text="Hello world" 
233 |         />
234 | ```
235 | 
236 | #### XA2002 - Use Pascal Casing
237 | 
238 | This rule is under editing, waiting for comments.
239 | 
240 | 
241 | #### XA2003 - Suffix XAML names with a type indication
242 | ##### **Cause**
243 | An element is named without a type indication.
244 | 
245 | ```xml
246 | <Button x:Name="Checkout"
247 |         Text="Checkout" 
248 |         />
249 | ```
250 | 
251 | ##### **Rule description**
252 | 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.
253 | 
254 | 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.
255 | 
256 | ##### **How to fix violation**
257 | Suffix the element's name with a type indication.
258 | 
259 | ```xml
260 | <Button x:Name="CheckoutButton"
261 |         Text="Checkout" 
262 |         />
263 | ```
264 | 
265 | ##### **Related rules**
266 | 
267 | - **XA2004** Do not use a precise type indication suffix, unless it's required
268 | 
269 | #### XA2004 - Do not use a precise type indication suffix, unless it's required
270 | ##### **Cause**
271 | An element's name indicates a precise type, however no code uses any type-specific properties/methods.
272 | 
273 | ```xml	
274 | <StackPanel x:Name="ActionsStackPanel">
275 |     ...
276 | </StackPanel>
277 | ```
278 | 
279 | ```
280 | ActionsStackPanel.Opacity = 0;
281 | ```
282 | 
283 | ##### **Rule description**
284 | 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.
285 | 
286 | For a lot of use cases, you don't need to know the exact element type. Let's see it in an example: 
287 | ```xml	
288 | <StackPanel x:Name="ActionsPanel">
289 |     ...
290 | </StackPanel>
291 | ```
292 | 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`.
293 | 
294 | 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.
295 | 
296 | ##### **How to fix violation**
297 | Remove precise indication suffix.
298 | 
299 | #### XA2005 - Name only nodes used in code-behind, element binding or animation
300 | ##### **Cause**
301 | An element defines a name and nobody uses it.
302 | ```xml	
303 | <StackPanel x:Name="ActionsPanel">
304 |     ...
305 | </StackPanel>
306 | ```
307 | 
308 | ```
309 |     ...
310 | ```
311 | 
312 | ##### **Rule description**
313 | 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.
314 | 
315 | ##### **How to fix violation**
316 | Remove `x:Name` or `x:Key` attribute.
317 | 
318 | ```xml	
319 | <StackPanel>
320 |     ...
321 | </StackPanel>
322 | ```
323 | 
324 | ### XA3x. Maintenability
325 | 
326 | #### XA3001 - Use the rule of 3 to decide if a value must be declared as a resource
327 | ##### **Cause**
328 | A property value is used at least three times.
329 | 
330 | ##### **Rule description**
331 | 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.
332 | 
333 | ##### **How to fix violation**
334 | 
335 | - Move the value to a resource, 
336 | - Replace all value usage by a StaticResource binding.
337 | 
338 | #### XA3002 - All the implicit styles must be placed at the top of the file and must be annotated with a comment
339 | ##### **Cause**
340 | An implicit style is declared elsewhere on a page/resource dictionary.
341 | 
342 | ##### **Rule description**
343 | A violation of this rule occurs when an implicit style is declared anywhere on a page/resource dictionary file, except at the top.
344 | 
345 | 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.
346 | 
347 | As these styles have a broad impact, they must be declared first and commented properly to give them visibility.
348 | 
349 | ##### **How to fix violation**
350 | If the style is used throughout the file:
351 | - Move the style declaration to the top of the `Resources` element,
352 | - Add a comment before the style declaration, stating the implicit nature.
353 | 
354 | If the style is used only on a portion of the file:
355 | - Make the style an explicit style,
356 | - Add the proper style binding in all involved controls.
357 | 
358 | 
359 | ### XA4x. Resource file organization
360 | 
361 | The following rules are under editing.
362 | 
363 | #### XA4001 - Put the default styles within App.xaml, put the others styles in another file
364 | #### XA4002 - Within a resource file, declare the elements in the following order
365 | ```
366 | <!-- #Constants -->
367 | <!-- #Colors -->
368 | <!-- #Brushes -->
369 | <!-- #Converters -->
370 | <!-- #Objects (such as Data) or commands (for ribbon),etc. -->
371 | <!-- #Styles -->
372 | <!-- #DataTemplates -->
373 | ```
374 | 
375 | ## Guideline authors
376 | 
377 | Please see [repository contributors](https://github.com/cmaneu/xaml-coding-guidelines/graphs/contributors).
378 | 
379 | 
380 | ## Work in progress
381 | 
382 | Please see [open issues](https://github.com/cmaneu/xaml-coding-guidelines/issues?state=open).
383 | 


--------------------------------------------------------------------------------