CSS GuideLines, part 1. Syntax and formatting

Introduction

CSS is not perfect. At first it seems that it is easy to learn, but working on a real project you will encounter many problems. We can't change the way CSS works, but we can change the code we write.

When working on large long-term projects involving dozens of developers with different specialties and skills, it is very important to follow certain rules. For the coder, these rules look like this:

• The developer must write the supported code;
• Developer must write transparent, readable code;
• The developer must write scalable code.

There are many techniques that we must use to comply with these rules. CSS GuideLines contains basic guidelines and approaches that will help us follow all of these rules.
')

The importance of code design guidelines

The code design guide is a valuable tool for teams that:

• develop and maintain products for a specific time;
• have developers with different levels of skills and with different specialties;
• have a certain number of developers constantly working on something;
• regularly hiring new developers;
• have a certain number of sources, which are constantly working with different people.

On any major projects with a large development team, everyone should strive to standardize their code.

A good guide to code design will allow you to achieve the following:

• Establishing a code quality standard for all sources;
• Ensuring consistency between sources;
• Following standards by all developers;
• Increase productivity.

Code design guidelines should be mastered and applied by all developers, and any deviations from the rules should be justified.

Disclaimer

CSS StyleGuide is a compilation of required techniques and methodologies. This is just a collection of recommendations tested on my personal experience. To use them or not is up to you.

Syntax and Formatting

One of the simplest types of code design guidelines (hereinafter referred to as the style guides, approx. Translator) is a set of rules regarding syntax and formatting. The presence of rules for the design of CSS-styles means that the code will always be clear to all members of your team.

Clean code gives a feeling of purity . It is much more pleasant to work with clean code, this code encourages other team members to also follow the standards of writing code. Dirty code is terrible and disgusting, nobody will want to work with it.

Ideally, developers should use:

• 4 spaces for indents. It is spaces, not tabs;
• Lines no longer than 80 characters;
• Multi-line CSS;
• Effective use of empty space.

Let's take a consistent look at the rules regarding code formatting.

Splitting into multiple files

After the rapid growth of the popularity of CSS preprocessors, many developers began to break their CSS code into separate files more often. Even if you do not use preprocessors, it would be nice to put the independent parts of the code in separate files and then merge them into one file when building the project (for example, using Grunt or Gulp).

If for some reason you refuse to use multiple files, the following steps may require minor adjustments.

Table of contents

Adding a table of contents in the CSS files is quite labor intensive, but these costs are more than worth the cost. Yes, the developer will need diligence to correct the table of contents in time and keep it up-to-date. But the whole team will get a single table with information about what is contained in the CSS file, what it does and in what order the styles are located in it.

For example, the simplest version of the table of contents is to add the section name and its description:

/** * CONTENTS * * SETTINGS * Global...............Globally-available variables and config. * * TOOLS * Mixins...............Useful mixins. * * GENERIC * Normalize.css........A level playing field. * Box-sizing...........Better default `box-sizing`. * * BASE * Headings.............H1–H6 styles. * * OBJECTS * Wrappers.............Wrapping and constraining elements. * * COMPONENTS * Page-head............The main page header. * Page-foot............The main page footer. * Buttons..............Button elements. * * TRUMPS * Text.................Text helpers. */ 

Naturally, on many projects, the table of contents may be much larger, but I hope this example shows how the table of contents in the main CSS file of a project can give the developer an idea of ​​what, where and how is used in the project.

80 character line width

If possible, it is advisable to limit the lines in the CSS files to 80 characters. Reasons to do so:

• The ability to keep in front of a few open files, placed next to each other;
• The ability to view CSS on sites such as Github, or in a terminal window;
• Providing a comfortable line length for adding comments.

 /** *  —   .    CSS-  .  *   ,      80 , *      . */ 

It should be noted that there are exceptions to this rule - for example, strings with long URLs.

Code Section Naming

Every major section of CSS should start like this:

 /*------------------------------------*\ #SECTION-TITLE \*------------------------------------*/ .selector {} 

Adding the "#" symbol at the beginning of the section name will allow us to search the file much faster. There is a possibility that the query “SECTION TITLE” will return many results, while a query with a grid in the beginning will return us only one desired result. You should also leave a blank line between the section name and the first selector.

If you are working on a project in which each section is placed in its own separate file, then the section name must be at the very beginning of this file. If in your project there are several sections in one file, then separate the last selector and the name of the new section with five empty lines. This allows you to significantly improve the readability of the code, especially when viewing long files.

 /*------------------------------------*\ #A-SECTION \*------------------------------------*/ .selector {} /*------------------------------------*\ #ANOTHER-SECTION \*------------------------------------*/ /** * Comment */ .another-selector {} 

Anatomy of CSS rules

Before we talk about how developers should write CSS rules, let's clarify the terminology used:

 [] { []: []; [<----->] } 

For example:

 .foo, .foo--bar, .baz { display: block; background-color: green; color: red; } 

In this piece of code you can see:

• Linked selectors on the same line, unbound selectors on different lines;
• Space before the opening bracket ({);
• Properties and their values ​​on a single line;
• Space after the colon associated with the property;
• Each property declaration and its value on a new line;
• The opening bracket is on the same line as the last selector;
• The first property declaration is on a new line after the opening bracket;
• The closing bracket is on a separate line:
• Each ad has a space of 4 spaces;
• The semicolon is immediately after the property value, without a space.

This way of designation is generally accepted and universal method (excluding the number of spaces to indent; many developers prefer to use two spaces instead of four).

Thus, the example below will be incorrect:

 .foo, .foo--bar, .baz { display:block; background-color:green; color:red } 

Problems from this example:

• Tabs instead of spaces;
• Unrelated selectors on one line;
• Opening bracket on a separate line;
• The closing bracket on the same line as the last declaration;
• Semicolon (by the way, it is optional in the last ad) at the end of the last ad is not worth it;
• No spaces after the colon.

Multi-line CSS

CSS should always be written in a few lines, with the exception of very specific circumstances. Benefits:

• Reducing the risk of conflicts when merging ads due to the fact that each ad is on a separate line;
• More reliable and readable diffs, because one line carries only one change.

Exceptions to this rule are fairly obvious. For example, you can write everything on one line in the case when there are several similar sets of rules with only one declaration inside:

 .icon { display: inline-block; width: 16px; height: 16px; background-image: url(/img/sprite.svg); } .icon--home { background-position: 0 0 ; } .icon--person { background-position: -16px 0 ; } .icon--files { background-position: 0 -16px; } .icon--settings { background-position: -16px -16px; } 

These types of rules can be written on one line, because:

• They still follow the rule of one change on a single line;
• They are similar enough to each other to combine them into one block of code; they should not be read with the same care as other independent rules.

Indentation

Just as you indent your ads, indent the associated rule sets as well:

 .foo {} .foo__bar {} .foo__baz {} 

Because of this, the developer will immediately see that .foo__baz is located inside .foo__bar, which, in turn, is inside .foo. This way of simulating the DOM tells developers a lot about where the class is located, so you don’t have to open the markup every time and look for the right piece of code.

Indentation in Sass

Sass provides the ability to put rules into each other. This means that writing the following scss code:

 .foo { color: red; .bar { color: blue; } } 

... we will get the following compiled CSS:

 .foo { color: red; } .foo .bar { color: blue; } 

When working with Sass, you should use the same 4 spaces for indents, as well as leave a blank line before and after the nested rules. By the way, nesting in Sass should be avoided. This will be discussed in the following sections.

Alignment

If possible, align similar lines with properties:

 .foo { -webkit-border-radius: 3px; -moz-border-radius: 3px; border-radius: 3px; } .bar { position: absolute; top: 0; right: 0; bottom: 0; left: 0; margin-right: -10px; margin-left: -10px; padding-right: 10px; padding-left: 10px; } 

This greatly simplifies the life of developers whose text editors support editing multiple lines at the same time.

Reasonable use of empty space

As with the use of indentation, we can give the developer a lot of information by correctly using the empty space between the rules.
Use:

• One blank line between related rule sets;
• Two blank lines between unbound rule sets;
• Five blank lines between sections.

Example:

 /*------------------------------------*\ #FOO \*------------------------------------*/ .foo {} .foo__bar {} .foo--baz {} /*------------------------------------*\ #BAR \*------------------------------------*/ .bar {} .bar__baz {} .bar__foo {} 

It should never happen that there is no empty line between the rules. The example below is wrong, so do not do it:

 .foo {} .foo__bar {} .foo--baz {} 

HTML

Given the close relationship between HTML and CSS, for my part it would be wrong not to specify some points regarding the markup.

Always frame attributes with quotes, even though the code will work without quotes. Just the format with quotes is most familiar to most developers, and this format allows you to avoid many mistakes.

This code will work:

 <div class=box> 

But it is preferable to use such code:

 <div class="box"> 

When writing multiple values ​​to an attribute, separate these values ​​with two spaces:

 <div class="foo bar"> 

When several classes are related to each other, consider how they are framed in brackets:

 <div class="[ box box--highlight ] [ bio bio--long ]"> 

This is not a strict recommendation, and I am still testing it in my projects, but this method entails a number of advantages. Read more about this in the article "Grouping related classes in markup . "

As is the case with our style sheets, empty space can also be used in the markup. For example, why not split important content sections in five empty lines:

 <header class="page-head"> ... </header> <main class="page-content"> ... </main> <footer class="page-foot"> ... </footer> 

Separate independent, but closely related parts of the markup with a single blank line:

 <ul class="primary-nav"> <li class="primary-nav__item"> <a href="/" class="primary-nav__link">Home</a> </li> <li class="primary-nav__item primary-nav__trigger"> <a href="/about" class="primary-nav__link">About</a> <ul class="primary-nav__sub-nav"> <li><a href="/about/products">Products</a></li> <li><a href="/about/company">Company</a></li> </ul> </li> <li class="primary-nav__item"> <a href="/contact" class="primary-nav__link">Contact</a> </li> </ul> 

This method improves the readability of the code, and also allows some text editors (Vim, for example) to easily manipulate such parts of the markup.

Materials for additional study

• "Grouping related classes in markup"

Continued: CSS GuideLines, part 2. Commenting code