A theory about Web Application Markup entropy over time

by Mark Thompson

I have been on a web development team that has been working a business application for 4 and a half years. Over that time, we’ve seen tech change from RequireJs to Webpack, moving to TypeScript and the introduction of KnockoutJs components, among others. Our team has grown from a core of 3 to multiple feature teams with some staffed by contractors for shorter periods. The code base and approaches have morphed as we learn and gain experience.

All that is great, but we find ourselves with mounting Technical Debt (see also my notes from HDC 2014 ). There are slightly different versions of HTML + CSS elements, different variations of css classes and combinations and of course some code feels older. All of this leads to some confusion on which page is the best to look at for examples (we usually say the newest version) and some re-work as we see things in pull requests.

I’ve been reflecting on what my team has been doing in the current project. I was also talking to someone at Omnitech about their opportunity to re-organize a site that has been around for a long time and will continue to be worked on.

How do we improve? How do we pay down technical debt, add new features, increase velocity and avoid re-work (waste)? How do we avoid getting into a state where the markup is too much of a mess to work with easily?

I think we first need a way to measure and a goal to work towards. Just like the term “technical debt” gives common terminology for developers and managers, maybe there is a way to discuss this form of debt.

I have a theory

What if we can describe entropy in the CSS and HTML of a web application in similar terms as database normalized form ? I’m assuming you are familiar with the term. It’s one of the first things I remember learning after college (maybe I should have learned that in college…). If not take a moment to look at the different forms .

If Web Application Markup “Normalized Form” (WAM NF) can be described by:

the HTML plus CSS

(possibly plus framework (Angular, React, Aurelia, Vue etc.) binding code but we’ll ignore that for now)

And the levels of WAM NF are defined as:

1. (10 points) style for most styling in the HTML, lack of CSS usage.
2. (5 points) CSS classes all in one big file (or a few big files) that are mostly unique to each page, with a few styles scattered about for slight modifications.
3. (3 points) Common CSS Classes used throughout the HTML. Very little to 0 HTML style usage.
4. (2 points) A style guide / UX Reference page or Atomic Design (all new elements are added in the style guide, this is the source of truth for how an element or set of elements are put together). The team maintains discipline to keep this up-to-date.
   1. CSS split into files that are related to their usage. Ex: layout, text, images, each page
5. (1 point) Small re-usable components (web, Angular, React, Aurelia, Vue etc.) with isolated CSS for the component and shared for common pieces. Also has a style guide / Atomic Design.

Year started or last major refactor = yearStartedTechChoicesHit

• 20: 1990 - 2000
• 15: 2000 - 2005
• 4: 2005 - 2010
• 3: 2010 - 2015
• 1: 2016 - current year (depends on what tech changes are going on)
• 0: brand new

then min(1, (years since start + yearStartedTechChoicesHit)) * (WAM NF Points) = the level of entropy

where entropy is shown through slight variations of the HTML and CSS, not knowing which version of that element is the best, and the amount of discussion around having to start over/find a new system

These forms can be used to evaluate the current state of a project, help formulate short and long term goals, and help teams recognize the constant creep of entropy.

Very simple examples of each form

1) Most styling in the html

    <div style="border: 1px solid red; padding: 5px;">
        <h1 style="font-size: 24px">My App</h1>
    </div>

Hopefully you’ve never had to maintain html like this. At least since the 90’s.

2) CSS Classes mostly unique

    <div class="body">
        <h1 class="header">My App</h1>

        <div style="margin: 5px;">
            <h2 class="sub-header">Sub header</h2>
        </div>
    </div>

    .body {
        1px solid red;
        padding: 5px;
    }

    .header {
        font-size: 24px;
        color: orangeRed;
    }

    .sub-header {
        font-size: 20px;
        color: blue;
    }

3) Common CSS Classes used throughout the HTML

    <div class="body">
        <h1 class="header">My App</h1>

        <div style="margin: 5px;">
            <h2 class="sub-header">Sub header</h2>
        </div>
    </div>

    // layout.css
    .body {
        1px solid red;
        padding: 5px;
    }

    // text.css
    .header {
        font-size: 24px;
        color: orangeRed;
    }

    .sub-header {
        font-size: 20px;
        color: blue;
    }

4) A style guide or Atomic Design is the source of truth

    // simple style guide, others would copy from here
    <div>
        <h1 class="header">Header look like this</h1>
        <h2 class="sub-header">Sub Headers look lik this</h2>

        <span>Regular text use span</span>
    </div>

    <div>
        <span>Text font families we use are: </span>
    </div>

    <div>
        <menu class="mainMenu">
            <div class="menuItem">Item 1</div>
        </menu>
    </div>

Css would be in multiple files like #3

5) Small re-usable components

I chose Aurelia , but this can be any framework or tool.

    export class MyAureliaButtonComponent {
        text = "This is Header";
        content = "This is content";

        click(){
            alert('clicked!!');
        }
    }

<template>
   <button class="myButton"  click.delegate="click">Click Me!</button>
</template>

    .myButton {
        margin: 0;
        padding: 8px 18px;
        border: 1px solid green;
        border-radius: 4px;
        color: orange;
        text-align: center;
        text-decoration: none;
        font-family: inherit;
        font-weight: bold;
        font-size: 14px;
     }

A Fictional Example

The dev team from Calormen Tech has been working on a web application since 2015. They used Asp.Net MVC Razor with some jQuery to create the application. They have a lot of style tags and each page has its own version of nested divs. CSS classes are unique to each page, but there are a few common CSS files when that was realized.

WAM NF Score = (3 + 3) * 5 = 30

The team wants to reduce this score. There are several options they consider.

1. Re-write and use Angular/React/Vue/Aurelia.
   1. This would reduce years since start to 0 and yearStartedTechChoicesHit to 0
   2. Major challenges are choosing a framework, bridging to old and keep making new features at the same time. You also have to convince your manager, who has to make a business case for it.
2. Move down the NF steps (to lower numbers).
   1. This can be done in steps. First identify common elements in the pages. Then move style usage into re-usable CSS classes. While you’re at it, you might as well create a style guide/Atomic Design reference.
   2. In this case, VueJs might help move away from jQuery making it easier to create components (and clean up a bunch of code to, I considered +10 for jQuery mess, but this post isn’t about JavaScript code :-)).
   3. Theory that eventually using native WebComponents will help them avoid having to do a full framework re-work (I don’t know if that would be the case or not).

Other factors

There are many other factors that could be added into the formula, but I left the formula simple for now.

• Team member turnover
• number of feature teams and contractor turn over
• Changing requirements
• Do you do Code Reviews and Pull Requests?

Other Tools

CSS Variables and CSS tools such as SASS or LESS or Post-CSS may help reduce entropy.

Bootstrap or Material Design CSS frameworks that reduce the need to write the CSS yourself. Any code you don’t write is better

I favor data binding over jQuery DOM manipulation and think KnockoutJs or VueJs or a framework would help reduce entropy in JavaScript code.

Is there a similar formula for code?

I believe there is a way to apply this to the code written for server-side and the JavaScript for client-side development. That would be a different article and take more thought to come up with that. There are Code Metric tools in Visual Studio and Sonar Qube that can help you determine, track and manage your technical debt.

Other links I’ve found recently

• https://blog.jamesmichaelhickey.com/refactoring-legacy-monoliths-part-2-convincing-management/
• https://einarwh.wordpress.com/2015/12/05/technical-debt-isnt-technical/
• Clean Code by Bob Martin is a great resource
• Squad Health Check model – visualizing what to improve - this activity could be helpful to figure out as a team where you stand (your code base and your team overall)
• Clean up your code with modular CSS
• CSS at Scale: LinkedIn’s New Open Source Projects Take on Stylesheet Performance - April 24, 2018

What do you think?

Let me know what you think in the comments!

Here’s a quote from my colleague Brian: “As time goes on within a project, CSS normalized form (NF) starts to “fall apart” and becomes less normalized than what it started with.  I have seen this in almost every app I have dealt with during my career but it seems to be less of a problem today than it was 10 years ago.  I think this is due to the accessibility of Bootstrap and other css frameworks.  With these frameworks, we have a good design basis to start with.  This starts projects off with a solid foundation.  With that foundation, the “one offs” that cause the CSS NF to fall apart don’t seem to come up as often.”