CSS GuideLines, part 2. Commenting code

In each project there are certain nuances and subtleties that are far from being remembered, and the worst thing that can happen to a developer is working with code that he did not write. Even memorizing the subtleties of your own code is only possible to a certain extent, not to mention someone else's code. That is why CSS needs to be commented .

CSS is a declarative language, and it is often difficult to understand:

• That some piece of code depends on another piece;
• What effect would entail changing a certain part of the code;
• Where else can you 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 touch on many quirks of CSS, such as turning on hardware acceleration using the transform property, but such things also complicate the understanding of what the code does.
')
Since CSS alone cannot be clear enough, developers really benefit from commenting on the code.

As a rule, it is necessary to comment on those places of the code that will be incomprehensible to the developer, if you pull them out of context. There is no need to make a note that color: red; make the text red. But, for example, if you use the overflow: hidden; property overflow: hidden; to clean up floats, not to hide content outside the block, you should add an explanatory comment.

High-level comments

For large comments describing a whole section or component, we use DocBlock-like multi-line comments that match our rule of 80 characters per line.

Below you can see a real example of commenting on the CSSWizardy site 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 commenting level should be used to describe an element in general: its state, on which this state depends, and so on.

An indication of style inheritance

When you work with a large number of files, then not always sets of rules relating to each other will be in the same file. For example, you can have a main class .btn containing only the main button styles (dimensions and indents, for example). This class is expanded in the components file, styles are added to it to give the desired appearance. We must designate these relationships between objects by indicating the inheritance of styles.

For example, in the file with the 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 of the code will not require much effort from the developer, and thanks to these comments, those who will have to work with your code will easily be able to understand the connections between the classes.

Low Level Comments

Often we need to comment on a specific line of code with the declaration of any property. For this we use footnotes. Under the link you can see an example of a more complex commenting code of the site header, 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 will not be displayed in the final style file when compiled. Take the rule to use such comments for code that also will not be compiled. For the code that will be displayed in 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 have documented variables (which will not be compiled) using the preprocessor comments, and for normal code, we used the standard commenting method. This method ensures that the compiled CSS files contain only relevant and necessary information for us.

Delete comments

It should be said that when using the code in production, all comments should be removed, and the CSS itself should be minimized before the deployment.

Previous part: CSS GuideLines, part 1. Syntax and formatting
Next part: CSS GuideLines, part 3. Naming classes