Testing the new HTML writing style
So last month, Stanislav Kucharik joined our frontend team at Exponea. One of his first ideas was to change the way we write HTML templates. Read his article to learn about this new format, the rules that apply to it, and the reasons why to use it. Here are my personal thoughts on the new format of HTML templates after using it for a while.
Background
At Exponea, we are using the ⚙️ Angular framework to power the frontend of our application. For a very long time, we have written the HTML templates of the components like this:
There are a couple of problems with this approach to HTML templates. First, it’s hard to add new attributes to a component or an element. You have to find the closing > and insert it before that. Sometimes the component has so many attributes already that the one you are trying to add is already there. You missed it because it’s hidden somewhere in the line with other attributes. Second, it really messes with the Git diff when you change attributes. Even when you add or remove a single input for a component, the whole line is modified and Git shows it like that. And third, when the component has a lot of inputs and outputs, it would have a few very long lines with these attributes. This violates the principles of clean code — some of the important parts of code are hidden near the end of very long lines (and as you scan the code, you mostly look to the beginning of lines), and the different parts are not clearly separated from each other, i. e. the component name and its attributes are mashed together.
Improving the Templates
To fix the issues mentioned above, Stanislav proposed a few ideas about how to change the HTML templates:
- Place each attribute on a separate line
- The closing
>should also be on a separate line - The
classshould always be first
Here is the same HTML template rewritten to follow these rules:
Right off the bat, you can see that the code is much more readable. This is a short code sample but you can imagine how this improves the readability of very large component templates. Let’s discuss the 3 rules and how they improve the code.
👉 Place each attribute on a separate line
This is the main rule. Placing each attribute on a separate line not only significantly improves the readability of the code but it also simplifies the modifications you make. If you want to add an attribute, just create a new line. Removing an attribute also means removing a line. Git is happy, programmers are happy, it’s a win-win situation. We have only one exception to this — when there’s only one short attribute, you can keep it inline (like the single class attribute on the first line).
👉 The closing > should be on a separate line
Having the > on a separate line makes it super easy to add new attributes and reorder the existing ones. If instead, it was on the same line as the last attribute, it would be much harder to spot, and you would have to break the line before it to add a new attribute. By having the > on a separate line, you can clearly see where the component ends and its children start.
I also use Vim to edit the source code. This makes it very easy to move the attributes around, add new attributes, and delete them.
👉 The class attribute should always be first
This rule is there only because the class attribute is so common. If you are using classes to style the elements (and you should, more on that later), most of the elements in HTML will have a class. Having the attribute first makes it easier to find it and modify it.
Bonus: Rxjs Streams
You can apply the same principles to writing Typescript and RxJS streams. Here’s an excerpt from a project list component using RxJS:
You put each operator on a new line and also make the same for arrow functions you pass in. This improves the readability a lot 🤘.
New Team Members
It blows my mind how the new members of our team can easily bring up issues that we were blind to for a long time. It seems that we were already pretty comfortable with the code so we didn’t think much about how to improve the formatting. But as Stanislav joined the team, he noticed the issues right away and proposed changes that Exponea team embraced. Read more about Stano’s perspective in his story about the HTML formatting.
This is my first post here on Medium. If you like it, make sure to give it a 👏 and 👍 and follow me for more great posts. Have a nice day!
