Comments

CSS should be compiled with a pre/post processor today. This enables single-line // comments that don’t exist in the CSS spec.

Comment formats

Use single-line comments // comment instead of multi-line comments /* comment */. This lets you span legitimate comments with code you’d like to temporarily cancel out.

// Single line comments are great.
.hello {
    color: red;
}

/*
// Only use multi-line comments to enclose groups of code.
.goodbye {
    color: blue;
}
*/

DocBlock

/**
* Project Name
* https://example.com/project
*
* @author     Brendan Falkowski
* @copyright  2017 Gravity Department. All rights reserved.
*/


// Code...
  • Do not indent * to match first line.
  • Two spaces after params (align all params vertically).
  • Two blank lines after DocBlock.

Priority comments

Comments that contain critical info about the code as a whole. Usually follows the DocBlock for immediate visibility.

// **********************************************
// GravDept:
// This file is deprecated.
// **********************************************


// Code...
  • Sign the comment (if needed).
  • Divider to 50th column using * character.
  • Two blank lines before divider.
  • Two blank lines after divider.

Sections

// ==============================================
// Section
// ==============================================

// Code...



// ==============================================
// Another Section
// ==============================================

// Code...
  • Capitalize the label.
  • Divider to 50th column using = character.
  • Three blank lines before divider.
  • One blank line after divider.

Sub-sections

// ----------------------------------------------
// Sub-Section

// Code...


// ----------------------------------------------
// Another Sub-Section

// Code...
  • Capitalize the label.
  • Divider to 50th column using - character.
  • Two blank lines before divider.
  • One blank line after divider.

Breakpoints

// Code...

// ----------------------------------------------

@include bp (min-width, 600px) {

    // Code...

}

// ----------------------------------------------

@include bp (min-width, 1000px) {

    // Code...

}
  • Divider to 50th column using - character.
  • One blank line before divider.
  • One blank line after divider.

All together now…

Use comment blocks to define code hierarchy.

/**
* Project Name
* https://example.com/project
*
* @author     Brendan Falkowski
* @copyright  2017 Gravity Department. All rights reserved.
*/


// ==============================================
// Level One
// ==============================================

.alpha {
    color: red;
}


// ----------------------------------------------
// Level Two

.beta {
    color: blue;
}

// Level Three

.charlie {
    color: green;
}

// Element comment
.delta {
    color: black; // Attribute comment
}

// ----------------------------------------------

@include bp (min-width, 600px) {

    .charlie {
        color: aqua;
    }

}

Now let’s dig into the details: