Sally has been tasked with making the commenting feature in her company’s webapp be threaded up to 5 levels instead of only 2 levels. As she makes adjustments to the code, she collects an unprecedented number of browser tabs. Some of them point at her company’s production site, while others point at her development environment. In many of them, she enabled “super-user” mode, so she could more freely play with her app while making her changes.

So she goes on coding and messing with the data for most of the afternoon. She’s about ready to wrap up and head home for the evening when her boss walks in and asks, “Sally, lots of comments have gone missing. Do you know what happened?” Sally felt like she had swallowed a sack of doorknobs. In the midst of her coding spree, she mixed up some of her browser tabs and accidentally deleted live data. A lot of live data.

We tend to prefer convention over configuration, so when we first began using Bower to manage our front-end dependencies, we started with minimal configuration. While this nicely put the files in the expected places, it was a hassle actually using the assets in our Rails app.

Our basic initial approach was to symlink the assets that we wanted to reference from the bower_components directory into vendor/assets where Sprockets would notice them. While this worked in the short term, it was tedious to set up new packages, and was likely to break if the required assets were moved when upgrading dependencies.

Ultimately, this felt like a hack. We decided that there must be a better way. Thankfully there is.

A mobile-first approach to design can be good: it helps you focus and potentially simplify your requirements, which can translate into a better user experience. Likewise, a mobile-first approach to implementation can be good: it puts the more expensive tasks on the shoulders of clients that are more likely to be able to handle the extra load, which can also translate to a better user experience.

At Causes, we have been building things with a mobile-first approach both in terms of design and implementation with a goal of progressive enhancement. Since switching to this mode on the technical side, we have noticed that our code is easier to write and more coherent to read, both of which are big benefits for the engineering team.

So we’ve put together a little project that helps us write readable media queries in this way. We call it sass-enhance.

At Causes we like to make our code more maintainable by building reusable components. Part of this strategy includes assigning variable names to hex colors using Sass. This allows us to more easily reuse the same colors everywhere, which improves consistency and makes it easier to re-color the entire site when our design needs change.

To increase the visibility of these reusable components, we’ve been building out a collection of things that designers and engineers can reference, drop in to projects, and iterate upon. The code sits next to the rendered version, allowing people to easily see the implementation required to produce the result. We call this collection the component gallery. It helps us do more with less code, be more consistent, and iterate on global changes more easily and effectively.

When we started fleshing out the color variables we wanted to use throughout the site, it seemed natural to show these colors in the component gallery as Pantone color chips. That way, designers could reference the colors that we are using, we’d have a single place to see that all of the colors look great next to each other, and engineers could easily pluck variable names when implementing designs to match the mocks.

Telling browsers to load large JavaScripts asynchronously can significantly improve performance. This prevents the browser from blocking the rendering of the page, allowing it to be viewed more quickly. However, if you are loading dependent files asynchronously, such as a third-party service’s API, making the scripts work together is not automatic.

At Causes we use Facebook’s large (nearly 60 KiB gzipped) JavaScript API on our pages. Although they recommend loading it asynchronously, we were already putting our JavaScript at the bottom of the page and weren’t convinced that async would give us much additional benefit. However, after some non-scientific performance tests it appeared that switching to asynchronously loading the Facebook API could reduce the time to DOMContentLoaded by nearly a full second on our pages.

Always code as if the [person] who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability. —John Woods

Diving into a large, old piece of CSS typically is neither easy nor pleasurable. I find that the biggest challenges in working with old CSS often lie in understanding the purpose and interactions of the styles.

When styling new elements, we have the entire context of the implementation immediately available, and it is easy to write styles that make sense to us at that very moment. However, in a few weeks or to a fresh pair of eyes, what made a lot of sense at first might end up being a lot more cryptic. Without a clear understanding of the purpose and interactions of the styles, modifying stylesheets can be dangerous, tedious, and cumbersome. Therefore, it is important to communicate enough context so that future developers will be able to grok the code easily and make informed decisions.

At Causes, we have adopted the following practices which we believe have improved the maintainability of our stylesheets, reduced bugs, and increased developer velocity. When you have finished reading this, I hope that you will have a few more tools to help move your codebase toward greater maintainability.