|
| 1 | +# Part 0 - Overview |
| 2 | + |
| 3 | +In this workshop, we will focus on creating UIs with XAML. If you're not a fan of XAML and prefer to make the UI with C#, that's a valid option, and you're welcome to do so, but we won't be covering that here. However, you might want to stick around (or skip to the end) and see if the XAML we end up with is more to your liking. |
| 4 | + |
| 5 | +Let's start by looking at an example [page from the final version](https://github.com/mrlacey/dotnet-maui-workshop-xaml/blob/main/Part%205%20-%20Custom%20Types/Finish/MonkeyFinder/View/DetailsPage.xaml). |
| 6 | +Now, compare it with [the version we started with](https://github.com/mrlacey/dotnet-maui-workshop-xaml/blob/main/Part%201%20-%20Fundamentals/Start/MonkeyFinder/View/DetailsPage.xaml). |
| 7 | + |
| 8 | +It looks very different: |
| 9 | + |
| 10 | +- It's much shorter: 27 lines rather than 56 |
| 11 | +- It contains fewer elements: 7 rather than 12 |
| 12 | +- Those elements include fewer attributes: 21 rather than 48 |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +Those changes are what's easily quantifiable, but there are some intangible differences too: |
| 17 | + |
| 18 | +- **It's now quicker to read**. And not just because there's less text on the screen. |
| 19 | +- **It's easier to understand**. Because you don't have to determine what the elements represent or why they're there. |
| 20 | +- **It's easier to support and modify (maintain)**. By understanding what's there and why, there's less chance of unexpected consequences when making a change. |
| 21 | + |
| 22 | +There are many ways to improve the **Monkey Finder** app you created as part of the .NET MAUI Workshop, but in this workshop, we'll only look at the XAML. |
| 23 | +This focus is because many people frequently overlook XAML, but it's one of the most criticized aspects of building apps with .NET MAUI. |
| 24 | + |
| 25 | +## 0.1 - Why it's important to look in detail at how we write XAML |
| 26 | + |
| 27 | +XAML is often criticized as being overly complex and verbose. This is often due to the way it's written, but this doesn't have to be the case. If there are two different ways of writing something, one that takes six lines and another that only requires a single line, and you choose to use the longer version, complaining about the need for extra lines is, at best, misplaced. However, some people never learn that the shorter option is available. That's what this workshop is here to show you. |
| 28 | + |
| 29 | +Many people are unaware that there are multiple ways of writing XAML, and I've met very few developers who have ever thought about what "good XAML" looks like. |
| 30 | + |
| 31 | +If you haven't considered this before, take a moment now to consider what makes a good XAML file. |
| 32 | + |
| 33 | +It's ok, I'll wait. |
| 34 | + |
| 35 | +... |
| 36 | + |
| 37 | +... |
| 38 | + |
| 39 | +... |
| 40 | + |
| 41 | +... |
| 42 | + |
| 43 | +What did you come up with? |
| 44 | + |
| 45 | +Here's my list. |
| 46 | + |
| 47 | +Good XAML should be: |
| 48 | + |
| 49 | +- **Clear** - so it's easy to read and understand. |
| 50 | +- **Concise** - so there's no unnecessary duplication or unnecessary text. |
| 51 | +- **Consistent** - which makes it easier to read and understand. |
| 52 | +- **Self-describing** - so it doesn't need extra comments or time spent deciphering the complex nested XML. |
| 53 | +- **Maintainable** - which results from all of the above. |
| 54 | + |
| 55 | +Hopefully, you can appreciate that none of my points about what makes good XAML are specific to XAML but apply to _any_ programming language. |
| 56 | + |
| 57 | +These points will help you write good code in any programming language. And yes, I do consider XAML to be a programming language. No, it's not Turing-complete, and it's not capable of many things that other programming languages are. Still, it's text files that we pass to the compiler and ultimately end up helping to create our application. When we think of XAML files this way, it's clear that we should be treating them with more care and attention. |
| 58 | + |
| 59 | +If you're new to working with XAML and aren't familiar with some of the problems I've already hinted at, I'll show bad examples in the coming parts so you can see the types of issues you can avoid. |
| 60 | + |
| 61 | +## 0.2 - Why is this workshop necessary? |
| 62 | + |
| 63 | +If you're one of the people who has never before considered what counts as "good XAML," then it should be obvious why this is important. |
| 64 | + |
| 65 | +From a broader perspective, I think there are three factors that have led to the widespread use of low-quality XAML today. |
| 66 | + |
| 67 | +1. Developers treat XAML as the designer's responsibility - and designers don't care about XAML. |
| 68 | +2. XAML was originally intended to be written by tools and not by hand. |
| 69 | +3. There are very few examples of what "good" can look like or effort to improve things. |
| 70 | + |
| 71 | +### 0.2.1 - Whose responsibility is XAML? |
| 72 | + |
| 73 | +I'm sure you're an exception to these generalizations, but many (most?) developers don't spend much time and effort focusing on the UI of their applications. The design and styling of the UI often falls to other people (designers), and they are not the ones who implement the designs. This disconnect means that no one person takes full ownership of the code used to implement the UI, and as long as the running app matches the images created by the designer, everyone can move on to other things (that they'd rather be doing.) |
| 74 | + |
| 75 | +Break the habit and take responsibility for what your XAML files look like. You'll benefit in the future when you come to modify them. |
| 76 | + |
| 77 | +### 0.2.2 - Write for humans |
| 78 | + |
| 79 | +In 2006, when XAML was first released (as part of WPF), the intention and expectation was that developers would use specific design-related tools to create their UIs with XAML and not write it all by hand. Over time, we've lost many of these design tools, and now there is little option (especially for .NET MAUI) other than to write XAML by hand. Elements defined with multiple levels of nesting and over many lines aren't a problem if you only see the UI through a design tool, but if you have to write that by hand (even in an editor with intellisense) it's far from ideal. |
| 80 | + |
| 81 | +You are not a robot. Your XAML will need to be read by other humans. Therefore, it makes sense to optimize writing XAML so that it's easier and simpler for people to write and read. The tooling doesn't have a preference for how the code is formatted, so you can use what's easiest (and best) for you and your team. |
| 82 | + |
| 83 | +### 0.2.3 - We can make things better, together |
| 84 | + |
| 85 | +"It's only XAML. It doesn't matter." Until it does. |
| 86 | +When you have to explain why what should be a simple change to the UI is taking ages because it's hard to alter one thing without unintended side effects. Or when you dread having to work with a particular code base because it's so hard to work out what the existing code does. |
| 87 | + |
| 88 | +These are scenarios that have been shared with me many times. But it's not our fault: |
| 89 | + |
| 90 | +- Over the years, very little time has been spent teaching more than the fundamentals of writing XAML. |
| 91 | +- There is a lack of samples and examples we can look at to see XAML being done well. |
| 92 | +- There are only a handful of people who have built tools to make working with XAML easier. |
| 93 | +- And, the effort to change or evolve the language has been minimal. |
| 94 | + |
| 95 | +While these are why we're in this situation, they don't excuse it. |
| 96 | + |
| 97 | +We still need to create applications we can easily modify and maintain. It should not be expected that UIs are hard to change without much effort, testing, and unintended consequences. |
| 98 | + |
| 99 | +There is a better way. And we need it. |
| 100 | + |
| 101 | +## 0.3 - What we'll be looking at |
| 102 | + |
| 103 | +Through the following parts of this workshop, we'll look at principles, "best practices," and techniques for writing good code (of any kind/language) and applying them to our XAML. |
| 104 | + |
| 105 | +- In part 1, we'll look at the fundamentals of setting up our code base. |
| 106 | +- In part 2, we'll look at applying the Single Responsibility Principle to our XAML. |
| 107 | +- In part 3, we'll see how "magic values" often permeate XAML files in ways that would not be tolerated in any other language. |
| 108 | +- In part 4, we'll explore how naming elements in XAML is especially important and how most people and samples get this wrong. |
| 109 | +- And part 5, we'll see how custom types (of varying levels of complexity) can make a big difference. |
| 110 | + |
| 111 | +## 0.4 - Disclaimer |
| 112 | + |
| 113 | +Many of the techniques, principles, and ideas covered in this workshop only have noticeable benefits when working on larger projects and applications. For a simple app like the **Monkey Finder** there is a perfectly valid argument that the XAML you already have is adequate for such an application. |
| 114 | + |
| 115 | +However, you are likely to want to build other applications that are larger and have more pages, views, and other functionality. Many of the problems people run into with building and maintaining larger code bases are that they try to write them like they do trivial apps and then wonder why they encounter issues. You wouldn't write a large, complex amount of C# in the same way you wrote your first Console app to display "Hello World". |
| 116 | + |
| 117 | +The aim of this workshop isn't to show how to change the XAML of the **Monkey Finder** app; _it's to show you principles you can apply to other, more complex apps_. |
| 118 | + |
| 119 | +My intention is not that you build apps with XAML in the ways shown in the original workshop (and elsewhere) and then modify that XAML to be easier to work with. Instead, it is that you get to a point where you can start with the better version. However, jumping straight into a different way of doing things can make it hard to understand why the reasons for the changes. Instead, we'll work through the list of principles to see how to apply them to existing XAML code. You'll then understand how to use them in the code you write in the future. |
| 120 | + |
| 121 | +## 0.5 - Getting started |
| 122 | + |
| 123 | +Now that you know why it's important to think about XAML like any other programming language |
| 124 | + |
| 125 | +Now that you're ready to focus on XAML let's look at some code! [Head over to Part 1 to get started](../Part%201%20-%20Fundamentals/README.md)! |
0 commit comments