The use of preprocessors to assist in generating well-formatted CSS has become a standard. With the addition of these tools, comes added complexity to our stylesheets. This makes it important to document and comment on the structure and specifics of the code to ensure transparency for both ourselves and other developers.

As mentioned above, commented code is very important and should be used for both PHP code, as well as within CSS. When working with preprocessors, such as SASS and LESS, there are two types of comments that can be used:

• Multi-Line Comments
• Single Line Comments

Multi-Line Comments

Example:

/* This is a variant
of a multi-line
comment. */

Multi-line comments start with  /* symbols and end after closing the */ symbols.

This type of comment can span one or many lines within your stylesheet. They are useful if you have several long comments and want to divide them onto separate lines.

Please Note: If you use multi-line comments in SASS or LESS files, they will be present in the compiled stylesheets.

Advantages:

• This type of comment works in standard CSS, PHP, and JS
• Good readability

Disadvantages:

• Comments will be present in compiled CSS

Single or One Line Comments

Example 1:

// Styles for a selector.
.selector {
   color: #fff;
   font-size: 16px;
   text-align: right;
}

Example 2:

.example-rule {
 float: left; // Styles for LTR direction property.
}

 

Single line comments start with // which signifies the start of a comment and works until the end of that line. Styles written on the next line will not be commented. If you want to comment on a few lines, you will need to include // on each of the lines you would like to include a comment on.

Advantages:

• Good for small or short comments
• Useful for commenting on specific styles
• Will not be presented in compiled CSS

Disadvantages:

• Only spans one line

When you are working with optimized and minified stylesheets, using single line comments is the best option, as they will not be included in the compiled CSS and will not add any weight to the compiled documents.

Suggested structure for Single Line Comments to make them more visible and divide for several groups.

As stated above, the use of only single line comments is suggested, especially when using a preprocessor. Your comment should start with // and a space after the slashes. The comment should begin with a capital letter and should end with a period.

There are three types of single line comments that should be used:

• A header section - a short description of the code that follows;
• Included elements on a page - list of blocks, panels, sections, etc;
• Inline comments - where it can be useful.

A Header Section

The beginning of each document should have a short description about styles and pages where it will be applied. We can use such structure:  "//**".

Example 1:

//** Global styles for blocks on medication page.

Included Elements on a Page

If you have structured elements like blocks, panels, views, sections, etc. you can provide a list of such elements for improved navigation. We can use such structure:  "//##".

Example 2:

//## Recent announcements.

//## Related documents.

//## Search.

Inline Comments

Add as many useful comments as you need. It should help others to easily understand your logic. If, for example, you have different blocks, views, panels, etc. you can divide them into groups implementing line comments. We can use the default structure:  "//".

Example:

// Search form.
.pane-pmi-medication-search {
...
}

Example of code for blocks.scss file using the three types of single line comments:

//** Global styles for blocks on site:
//## Contact Medical Agent.
//## Search.
//## What's new.
//## Related Formulas.
//## Other Resources.
//## Go To Medication Page.

// Contact Medical Agent.
.pane-contact-medical-agent {
 .pane-title {
   @include header-style-block();
 }

 .contact-options-wrapper {
   padding: 5px 5px 10px 15px;
 
   ul {
     list-style: none;
     padding: 0;
     margin: 0;
 
     li {
       margin-top: 10px;
     }
   }
 }
}
…

Example of code for style.scss file that includes other documents:
 

// Custom variables.
@import "variables";

// Bootstrap library.
@import "../bootstrap/sass/bootstrap";

// Compass mixins.
@import "compass";
 

// Theme specific.
@import "media";       // Media variables.
@import "mixins"; // Custom mixins.
@import "global"; // Global theme styles, colors, default sizes.
@import "header"; // Header and main menu.
@import "footer"; // Footer and copyright.
@import "popup"; // Popup styles.
@import "chosen"; // Chosen custom select styles.
@import "domain"; // Domain specific styles for FR and ES.
@import "blocks"; // Blocks styles like "Contact Medical Agent" and “Search”.
...

Example of hierarchy file organization:

Code of main "screen.scss" file:

// Core Styling.
@import "core/base";
@import "core/theme-variables";
@import "core/mixins.grid";
@import "core/mixins.device-size";
@import "core/mixins.grid-shorthand";
@import "core/mixins.util";
@import "core/mixins.retina";
@import "core/mixins.styles";
@import "core/fonts";
@import "core/normalize";
@import "core/global";

// Layout Styling.
@import "layout/**/*";

// Components Styling.
@import "components/**/*";

// Template Styling.
@import "templates/header-row";
@import "templates/navigation-row";
@import "templates/breadcrumb-row";
@import "templates/footer-row";

Screenshot of directory:

Benefits of a Readme file

Big projects require not only comments but also documentation and guidelines. If you have a special structure or specific implementation of styles you can create a README file and describe the problem or write a short tutorial. For example: we are working with some companies that provide us with their own platform. A compilation of files goes through Grunt and style modifications have specific steps and tricks. For faster understanding and modification in the future, you can create documentation. After reading the documentation, developers will be have a clear understanding of how to run, find, modify and add new styles or scripts. Creating a short tutorial will only take 5 to 10 minutes and will save time in the future by providing lasting support. With this type of resource, it makes it easier for all developers, including new ones, to begin work on a project.

Conclusion

We don't use plain CSS coding anymore - we use preprocessors to assist in simple and clean code creation. Preprocessors generate well-formatted CSS and makes our stylesheets easier to organize and maintain. SASS and LESS allow us to use nested rules, variables, mixins and more, which add a layer of complexity to our stylesheets. This is why commenting is so important. You should take care in adding comments to your styles so that other developers are able to easily navigate and understand your code. If you change or remove styles then you should update or remove the corresponding comments. Comments should always be correct and up to date. Well-commented code and documentation will minimize time in the future, as it keeps code clean and transparent, and makes stylesheets easy to navigate through.