One of the beauties of authoring code is that apart from basic syntax rules, formatting is flexible. But, we all know there are best practices for helping make certain code more readable, and more friendly for collaborator environments.

Here’s the basic styleguide that I’ve come to adopt for authoring my Sass files (SCSS flavor of course). You may like what I’ve come up with (then use it), or you may not like it (then make one of your own). Either way I hope it gets you to think more critically about how formatting your code can lead to efficiency for yourself, and for your team.

// Style category name
// -------------------------------------------/

.some-element {
    // styles for the `self` item at the top
    overflow: hidden;
    margin: 0 auto;
    background-color: #0099ff;
    border-bottom: 10px solid #fff;

    // When less than 3 properties leave them inline
    .some-child { background-color: #fff; display: block;

        // When 3 or more properties, add new lines and bracket after last
        &:first-child {
            // Group props onto 1 line for logical associations
            width: auto; height: 3em;
            margin: 0; padding: 0;
            display: block;
            position: absolute;
            top: 0; left: 50%; bottom: 0; }

        .some-child-again { width: 50%; height: 40px;

            element {
                display: block;
                color: inherit;
                text-decoration: underline; }

        }

}

// end style category name ------------/

I’ve arrived at this format over several years of writing and maintaining CSS or Sass on projects of all different scales, and I’ve found this approach to be most comfortable for authoring and maintaining, whether riding solo or rolling with a posse.

It’s influenced by a number of different CSS schools of thought, including Nicole Sullivan’s pioneering evanglism of OOCSS, Jonathan Snook’s very useful SMACSS method for large projects, Jeff Starr’s thoughts on micro optimizing your CSS, Mark Otto’s very simple and practicle Code Guide, and a touch of Kyle Neath’s method for CSS documentation called KSS.

My approach, not GitHub’s

To be clear, this is my personal preferred approach which I have used in the past on client projects, for employers, and for personal projects. However, it’s not the exact approach we take at GitHub. It’s close, but there are some small differences, like where I tend to combine multiple related properties on one line, or grouping less than two properties in general on one line.

If you’d like to learn more about how we author CSS (and SCSS) at GitHub, you should check out our public CSS Styleguide.