How to make your code easily maintainable with living style guides

Style guides of yesteryear are typically thought of as design-oriented documents focusing on branding and color usage. But with the advent of insanely large codebases for websites like Facebook or Google’s vast array of products, style guides have since evolved.

These days, living style guides contain always up to date documentation of the current code base and its use cases. With these documents we can write much more maintainable and reusable code while seeing instantly how optimized our code base is.

What’s in a living style guide?

Living style guides are similar to the older counterparts; they contain logo and branding information, color usage, as well as a general outline of code usage. The code outline section is where you can easily find duplicate or closely similar code and combine it to optimize your codebase, or view components already in use. Most guides either showcase a “log” style approach where every code instance is documented, or only the intentionally modular code is documented.

Not only do these guides focus on HTML and CSS, but also other languages that can be modularized for performance like JavaScript and PHP. A few solid examples of living style guides can be found at Github, Mozilla, and MailChimp. As you can see from those examples, it’s common to have either a page or sub-site to display use-cases side by side with the code for each component. This makes it easy to go and grab them when you need them, and for unfamiliar designers or developers to see how components work in an interactive fashion.

Starting your own living style guide

Beginning your own living style guide documentation from scratch may seem daunting, especially for larger projects. But typically there is a return on the investment of time required to get it done. Larger projects benefit immensely from a living documentation of site styles and code structure. Smaller projects have a less noticeable, but sometimes still worthwhile, return on your time investment. In either case, if you’re working on a project that may someday be handed off to another designer or developer it’ll make their day to see such documentation.

Start with the foundation

Components you use frequently are the best use-case for a living style guide, buttons come to mind immediately. A short list of things you may want to consider documenting are layout options (possibly outlining a grid system), typography, color usage, buttons and link styles, form styling, notifications or alerts, and list styling. Just about anything that may benefit from being reusable could be added essentially. When outlining, remember to keep things flexible. Never style an alert or button specific to one page or use-case, unless absolutely necessary. Instead, add modifier classes to build on the basic foundation for things like color, typography, or aesthetic changes. This way, you can always count on the .button class to designate a consistent width, height, and text size while allowing the modifier classes to change things particular to each use-case.

The goals of maintainable code

The purpose of maintainable code is to make things reusable and future-proof. Components such as notification bars, buttons, headers, and footers, are great examples of reusable code – Things you may use multiple times across the site, or on the same page. If you’re breaking old or already written code down to make it more maintainable after the fact, it’s actually pretty simple. Start by stripping away the CSS down to the basics. You should be left with a component class defining structural things like height, width, and position. While additional modifier classes can be used to change aesthetic things like color or typography. Additionally, if your project is using a body ID or class for each page, you can style unique use-cases on a per-page basis this way. Be sure not to resort to this practice too much though, as it can easily add weight to your style guide.

The KISS Principle is a design principle well suited for the modular development process as well. Writing simple, maintainable code is usually easiest by keeping your components simple. When it comes to simplicity, If it’s possible to make things more efficient and/or use less code while achieving the same result, our components should be written to do so. The end goals of a maintainable code structure is to have something reusable, small, and vastly more efficient than a non-maintainable counterpart.

Naming conventions in CSS

When it comes to working with a maintainable code structure, naming conventions become very important. Writing descriptive CSS classes will go a long way to ensure maintaining your code base will be an easy task. There is no limit on CSS class lengths, so use this to your advantage. Make sure to stick to a clear naming convention though, as mixing dashes vs underscores or camel case vs all lowercase names can easily get confusing. It’s usually a great idea to make your component classes very descriptive, while making the modifier classes less so. Below is an example of a button, a unique use-case rule, and modifier classes.

<a href="www.webdesignerdepot.com" class="“button"

/* This is a component class, it should only contain basic structural rules */
.button {
display: block;
width: 250px;
height: 48px;
line-height: 48px;}

/* This unique use-case outlines a button used on the homepage */
.homepage-cta-button {
display: block
margin: 0 auto 50px;
width: 180px;
height: 60px;
line-height: 60px;}

/* Below are modifier classes, these are added in addition to the component class to add color or other aesthetic changes */
.red {background: #C54F48}
.rounded {border-radius: 5px;}

Automated solutions

Automated style guide generators have started popping up left and right to help the push for style guides. Style Prototype is a SASS generator built by Ram Richard and Mason Wendell of Team SASS. It’s one of the better options out there at the moment, with similar generators like Hologram, Kalei, StyleDocco, and KSS also proving useful.

Automated vs hand-crafted

As always, there are pros and cons to using either method here. Automated solutions are quick and can be used after the fact, but they’re also sometimes strict. Hand-crafted style guides leave you knowing the ins and outs of everything, but take more time. Personally, the hand-crafted approach is best for me in most cases as it’s the most flexible in terms of working with other developers. But it’s certainly worth the time to try out some of the automated solutions, just to get an idea of how they work and what they say about your code.

Reviewing your code

Websites are never finished. We modify things, transition to new styles and trends, and in the end we can end up with a lot of code from past revisions. It’s important to take a moment and look back at the “end” of each revision to make sure things are as clean as they can be. At this point, I also like to throw each component (and modifier classes) in a Codepen to test browser support and make notes accordingly. This could save tons of time later if you’re designing a page with support constraints. While reviewing, also be sure to keep an eye out for components that may conflict with each other in odd ways or cause box-model problems.

Conclusion

In conclusion, style guides should result in code that is very manipulative and flexible, yet still easy to maintain and read. Considering how much time we must invest to reach such a result, living style guides have a much more quantifiable affect on larger projects than smaller ones. Complex or large projects benefit so much from all the optimization and performance increases that it’s well worth the time spent to reach said results. Creating a living style guide for a small website or project may not prove worthy of the time investment though.

In conclusion, we should all strive to write clean, maintainable code that focuses on future-proofing. Living style guides tend to encourage such a workflow and aide in making developers and viewers alike much happier.

Featured image/thumbnail, programming image via Shutterstock.

Dustin Cartwright

Dustin Cartwright is a UI/Web Designer & Front-End Developer from Baltimore, Maryland. He spends the majority of his time focusing on user experience research and is passionate about building things for the web.