Old Sites, NewTools

The tools and techniques available to Web developers have improved immensely in the last few years. Our jobs are easier and the Websites we build better because of editors like Atom.ioSublime Text, and VisualStudio Code, diff tools like Beyond Compare, version control systems like Git (and the de-facto home of open-source development based on it, GitHub), developer-focused browsers like Mozilla’s Developer’s Edition of Firefox and Google’s Canary Edition of Chrome, CSS processors like SASS and PostCSS, build tools like Gulp, Grunt, and Webpack, JavaScript libraries like React.js, AngularJS, and jQuery — I could go on and on.  That’s  a partial list of my daily toolkit. The full kit is larger and good options exist for every tool I use.

These tools can lost their edge, though, if we’re asked to add a feature to a site that was built five years ago (or a site that was built yesterday using methods from five years ago), and we might face the prospect of having to revert to what feels like sharpened rocks to get the job done. Revising legacy CSS files is where I first notice great tools becoming irrelevant and where the problem has loomed largest for me, and that’s what I’m going to talk about here.



Reviewing an existing and unfamiliar website in preparation for a revision, you often find huge CSS files which various developers with different skill levels have worked on over the years, typically adding new style rules to the bottom of the file to apply to new or modified features, occasionally with a comment, often with a comment consisting only of the date the rule was added. People rarely clean up a stylesheet — for the very good reason that cleaning up is likely to break things and a task budget almost never includes provisions for full-scale regression testing..

Modern tooling can’t solve it but can prevent us from adding to the problem. Here’s a sketch of an approach I’ve started adopting when asked to add a section or make revisions to an existing site with a large, legacy stylesheet. I’m often working in a WordPress environment so this example reflects that.

In  a WordPress environment, a stylesheet is required, must be named style.css, and must reside at the root of the theme folder. The folder structure looks like this:

- site root
  - some stuff
  - /wp-content
    - /themes
      - /mytheme
        - /style.css
        - other files and folders
      - other theme
    - other folders
  - other stuff

My general approach is to create a new folder withing the theme folder named css-partials and move the current style.css file, just as it is, into that new folder, renaming it to _style.css. The underscore at the beginning of the file name is a convention to indicate one element to be assembled into the final stylesheet — a “partial”. The folder structure now looks similar to this:

- site root
  - /wp-content
    - /themes
      - /mytheme
        - /css-partials
          - /_style.css
        - other theme files
        - /style.css

At the end of the renamed file, after the last style rule, I insert a directive like @import "_new-module.css"; which normally directs the browser to load the file specified, but which, here, will be a command to compile that specified file, along with others, into a single stylesheet. All of the mark-up for the new module or site section that I’m introducing goes into that new file and will be appended to the legacy stylesheet, now named _style.css.

In that partial stylesheet for the new module or section, the selectors, along with the HTML elements they correspond to of course, are carefully named so that they will never apply anywhere on the site except this new section/feature. That naming is an art all it’s own. I use a loose adaptation of the BEM naming convention and there are many good options.

To compile the legacy stylesheet with the new one(s), you need to use a build tool. Again, there are good options — I use Gulp. And with that I’ve introduced a huge universe comprised of Node.js and it’s accomplices. Explaining that is more than I’m willing to take on and implementing it in your work environment requires some effort, but once you have it in place you can use a CSS processor called PostCSS  pointed at the file css-partials/_style.css to compile the contents of that legacy code along with the contents of the new files that have been @imported in that file into a compacted (if you want), minified (if you want) style.css at the root of your theme folder to be read and applied by WordPress and your visitors’ browsers.

A substantial investment is required to learn to do this stuff. The payoff is huge — you get to use modern techniques for writing CSS, like variables and nesting, which improve productivity, ans, much more importantly, you can isolate your new CSS from the legacy styles and never touch (so never break) the legacy styles while developing new features.