CSS GuideLines, Part 2. Commenting on the code

Original author: Harry Roberts
  • Transfer
  • Tutorial


Each project has certain nuances and subtleties that not everyone remembers, and the worst that can happen to a developer is working with code that he did not write. Even remembering the intricacies of your own code is possible only to a certain extent, not to mention someone else's code. That's why CSS needs to be commented on .

CSS is a declarative language, and it is often difficult to understand:
  • That some piece of code depends on another piece;
  • What effect will entail a change in a certain part of the code;
  • Where else can I use a piece of code without new problems?
  • What styles a particular element inherits;
  • What styles can be ignored;
  • Where the developer intended to use the code.

This list does not even affect many CSS quirks, such as enabling hardware acceleration using properties transform, and such things also complicate the understanding of what the code does.

Since CSS alone may not be understandable enough, developers really benefit from commenting on the code.

As a rule, you should comment on those parts of the code that the developer will not understand if you take them out of context. There is no need to make a note of what color: red;will make the text red. But, for example, if you use a property overflow: hidden;to clear floats, and not to hide content outside the block, then you should add an explanatory comment.

High level comments


For large comments describing an entire section or component, we use DocBlock-like multi-line comments that conform to our 80-line rule.

Below you can see a real example of commenting on the CSSWizardy website header code.

/**
 * The site’s main page-head can have two different states:
 *
 * 1) Regular page-head with no backgrounds or extra treatments; it just
 *    contains the logo and nav.
 * 2) A masthead that has a fluid-height (becoming fixed after a certain point)
 *    which has a large background image, and some supporting text.
 *
 * The regular page-head is incredibly simple, but the masthead version has some
 * slightly intermingled dependency with the wrapper that lives inside it.
 */

This level of commenting should be used to describe the element in general: its state, what this state depends on, and the like.

Indication of style inheritance

When you work with a large number of files, the rule sets related to each other will not always be in the same file. For example, you may have a main class .btncontaining only the basic styles of the button (sizes and indents, for example). This class is expanded in the component file, there styles are added to it to give the desired appearance. We must identify these relationships between objects by indicating the inheritance of styles.

For example, in a file with main classes (objects):

/**
 * Extend `.btn {}` in _components.buttons.scss.
 */
.btn {}

In the file with child classes:

/**
 * These rules extend `.btn {}` in _objects.buttons.scss.
 */
.btn--positive {}
.btn--negative {}

Such commenting on the code does not require much effort from the developer, and thanks to these comments, those who have to work with your code can easily figure out the relationships between the classes.

Low level comments


Often we need to comment on a particular line of code with the declaration of a property. For this we use footnotes. Using the link, you can see an example of more complex commenting on the header code of the site, which was mentioned above. This way of commenting allows us to keep all the documentation in one place, and then just refer to the right place in the documentation, instead of writing a long comment directly in the code.

Preprocessors and commenting


In many, if not all preprocessors, it is possible to add comments that, when compiled, will not be output to the final stylesheet. Make it a rule to use such comments for code that also will not be compiled. For the code that will be output to the final file, use regular comments.

That's right:

// Dimensions of the @2x image sprite:
$sprite-width:  920px;
$sprite-height: 212px;
/**
 * 1. Default icon size is 16px.
 * 2. Squash down the retina sprite to display at the correct size.
 */
.sprite {
    width:  16px; /* [1] */
    height: 16px; /* [1] */
    background-image: url(/img/sprites/main.png);
    background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */
}

In this example, we documented variables (which will not be compiled) using preprocessor comments, and for regular code, we used the standard way of commenting. This way we are guaranteed that the compiled CSS-files will contain only relevant and necessary information for us.

Removing Comments


It should be noted that when using the code in production, all comments should be deleted, and CSS itself should be minified before the deployment.

Previous part: CSS GuideLines, part 1. Syntax and formatting
Next part: CSS GuideLines, part 3. Class naming

Also popular now: