Hey, fellow writers who work in MadCap Flare! Have you ever opened your CSS style sheet in a text editor and checked if it contains conflicting entries, style duplicates, or empty style definitions? Maybe there are unnecessary repetitions of a property assigned to child elements, but this property is already assigned to a parent element? (I had this problem with fonts and colors).
Being unsure of what is going on with your CSS, you might be surprised to find that, for example, after you changed one property, half of your document inexplicably changed its color or indentation level. And there you are wasting time trying to apply a quick fix that most probably breaks something else. It is only then that you finally realize that the CSS refactoring time has come.
CSS refactoring: why should we care?
Code refactoring is usually defined as “the process of rewriting code in order to make it more simple and reusable without changing its behavior” (Martin Fowler, Refactoring: Improving the Design of Existing Code). Being related to code, refactoring is usually discussed as a developers’ task. We, InfoDevs, should understand the basics of CSS refactoring as well because we work in authoring tools that rely on CSS, and it’s us who develop and maintain project style sheets.
Where to start: a roadmap
After analyzing several great resources about CSS refactoring (listed at the end of this post), I’ve put up a generic “refactoring roadmap”. Its steps are the following:
- Run your CSS through the tools for code quality analysis (some of the tools are mentioned further in this post).
- Identify what what needs to be changed.
- Make a schedule for changes (for example, save time for refactoring at the end of each sprint).
- Back up before changing anything.
- Create CSS guidelines or a list of rules for future use.
In my opinion, the first step of the suggested roadmap—code analysis—largely defines the next steps. Based on the results of the code analysis, you decide what exactly needs to be changed and create a schedule for changes. Therefore, in this post, I’ll focus only on the first and the last steps of the suggested refactoring roadmap—tools and guidelines.
Code quality analysis tools
Let’s take a closer look at the tools you can use to analyze your CSS style sheet.
Reports in MadCap Flare
You can start with MadCap Flare’s Reports. This feature provides a great analysis of basically all components of your project: you can view the list of unused images, unlinked topics, broken links, and so much more. In terms of CSS, Reports can help you find unused, undefined (empty), and duplicate styles.
To generate a report:
- Go to Project Organizer, expand the Reports node, and then double-click any of the existing report templates.
- On the report page, in the Styles section, select the “styles health” categories that you want to include in a generated report, and then click Generate.
I’ve used the Reports feature on one of my projects and found duplicate styles—several styles with identical properties, such as the following:
These online tools usually analyze your CSS against particular sets of rules and best practices. Even without a profound knowledge of CSS, you can check your style sheet for the following:
- Unused CSS rules.
- Empty rules, for example:
- Duplicate rules, for example:
- Variants of a single color – for example, multiple shades of blue instead of one.
- Zeros used with units of measure – according to the CSSLint default rules, the following should be avoided:
- Overly specific selectors – for example, class1 is more specific than .class1 and thus, less reusable. And p.class1.class2 is even more specific and less reusable.
For more information about CSS specificity, take a look at this specificity calculator.
Finally, you can open your CSS sheet in any text editor and examine it. Without any analytical tools, you can spot the following:
- Empty rules, for example:
- Hard-coded values. In the following example, instead of the line height of 24px, it is better to use the relative value 1.2:
- Different units of measure – in my case, it was a random mix of pixels and points within the same online output.
Write down your best practices
Project CSS refactoring is not a one-time event—it’s a continuous process. Add your most common mistakes to a refactoring checklist to go through regularly, for example, at the end of each sprint. Additionally, it’s a good idea to create your project’s CSS best practices document, where you can specify:
- What styles are used in particular cases.
- How new styles are added.
- How you add comments to the style sheet (if any).
- Whether you delete or comment out the unused rules.
- How specific your selectors can be.
- Any particular naming conventions (for example, capitalization rules).
Documenting your CSS rules is especially important when several authors contributing to a project have different understanding of CSS (or even different preferences).
To sum it up, do not just accept whatever has been crammed into your style sheet. Ask, read, and learn to make your styles error-proof, reusable, and clear to anyone.