XAML guidelines and best practices

Everyone has their own opinion on how source code should be structured and formatted.  What really matters when it comes to code is not saving the CPU a couple cycles, rather enabling others to read and understand what you’ve written.  This comes from Martin Fowler’s classic book Refactoring:

There is another user of your source code.  Someone will try to read your code in a few month’s’ time to make some changes.  We easily forget that extra user of the code, yet that user is actually the most important.  Who cares if the computer takes a few more cycles to compile something?  It does matter if it takes a programmer a week to make a change that would have taken only an hour if she had understood your code.

When it comes to XAML, there aren’t too many opinions/articles talking about best practices (compared to other languages/markup).  In fact, the definitive guide for XAML guidelines is Jaime Rodriguez’s (site) best practice web cast series and the resulting whitepaper (pdf).

XAML practices series, part1

XAML practices series, part2

XAML practices series, part3

Jaime’s whitepaper is a must read for anyone in the Silverlight space. 

Since my blog is less formal than a whitepaper, I’m able to give a stronger opinion on what I think are the best practices for XAML.  So, without further ado here are my thoughts on XAML:

Formatting

First and foremost, I think formatting is the number one concern. 

• Attributes should be on a separate line,
• x:Name should come first,
• and related attributes (such as HorizontalAlignment and VerticalAlignment) should be grouped.

Take the below code blocks, Figure-1 and Figure-2, show the difference between having all the attributes on the same line versus on different lines.  In my opinion, Figure-2 is much easier to digest than Figure-1.  By having the x:Name first, you can quickly identify what the element is.  Once you find the object you are looking for, you can then quickly identify related objects since they are grouped together (such as RadiusX and RadiusY, Width and Height, and HorizontalAlignment and VerticalAlignment).

The biggest complaint about Figure-2 is “wasted space”.  The code inflates from 8 lines to 30; however, to Martin Fowler’s point, it’s not about you or the computer, it’s about other people being able to read and quickly assimilate to your code.

Figure-1

  

Figure-2 

Naming conventions

Name everything

Try to specify an x:Name attribute for every element in XAML.  If nothing else, this will make you think if you really need the object.  For example, at times it’s tempting to embed a panel within a panel to achieve a specific layout.  In many instances I have caught myself doing this, mainly out of laziness.  After refactoring I find that if I tweaked a margin or used a different kind of panel, there would have been no need for the extra panel.  Forcing an x:Name on an object really makes you think of the purpose of that element.

Describe elements

Instead of pre or post-fixing element names, give them a descriptive name.  Instead of:

• btnSubmit use SubmitButton,
• grdContent use ContentPanel,
• stkPnlNav use NavigationPanel.

Programmers like using the pre-fix because you can quickly see all of the same type when using intellisense, and you can easily identify the type of an element.  Admittedly, I come from this camp; however it’s time to change.  A couple reasons for the change: 1.) designers will increasing be  working in Blend and they are not going to be geeks like most of us and pre-fix with the type 2.)descriptive names are much easier to read and understand the cryptic typed names (think stkPnl=StackPanel or me=MediaElement).

Lastly, give all panels the same post-fix because you never know if you will have to change the type of a panel.  I assure you, it’s an enormous pain, and large risk, to change the x:Name in a project.  For example imagine having to change “BufferGrid” to “BufferCanvas” to “BufferStackPanel”.  Not only do you have to change the XAML, you have to ensure all instances in the code are changed too.  Better to go with the generic “BufferPanel” and be done with it.

Disclaimer

Best practices should be followed to the T; however, there are times when we’re in a crunch and the guidelines fall the way side.  Best practices are designed to eliminate maintenance time and promote consistency.  I am certainly guilty of not following the above guidelines, however it’s my goal to follow these consistently as possible.