http://habrahabr.ru/post/235893/



В каждом проекте есть определенные нюансы и тонкости, которые помнят далеко не все, и худшее, что может случиться с разработчиком — это работа с кодом, который писал не он. Даже запоминание тонкостей своего собственного кода является возможным только до определенной степени, не говоря уже о чужом коде. Именно поэтому CSS надо комментировать.

CSS это декларативный язык, и часто бывает трудно понять:

• Что какой-то кусок кода зависит от другого куска;
• Какой эффект повлечет за собой изменение определенной части кода;
• Где еще можно использовать кусок кода без появления новых проблем;
• Какие стили наследует определенный элемент;
• Какие стили могут быть проигнорированы;
• Где разработчик намеревался использовать код.

Этот список даже не затрагивает многих причуд CSS, таких как включение аппаратного ускорения с помощью свойтсва transform, а ведь такие вещи тоже усложняют понимание того, что делает код.

Так как CSS сам по себе не может быть достаточно понятным, то разработчики действительно получают выгоду от комментирования кода.

Как правило, следует комментировать те места кода, которые будут непонятны разработчику, если вырвать их из контекста. Нет необходимости делать пометку о том, что color: red; сделает текст красным. Но, например, если вы используете свойство overflow: hidden; для очистки float'ов, а не для скрытия контента за пределами блока, то вам следовало бы добавить пояснительный комментарий.

Высокоуровневые комментарии

Для больших комментариев, описывающих целую секцию или компонент, мы используем DocBlock-подобные мультистрочные комментарии, соответствующие нашему правилу о 80 символах в строке.

Ниже можно увидеть реальный пример комментирования кода шапки сайта CSSWizardy.

/**
 * 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.
 */

Этот уровень комментирования должен использоваться для описания элемента в общем: его состояния, от чего это состояние зависит и тому подобное.

Указание на наследование стилей

Когда вы работаете с большим количеством файлов, то не всегда наборы правил, относящиеся друг к другу, будут находиться в одном и том же файле. Например, у вас может быть главный класс .btn, содержащий в себе только основные стили кнопки (размеры и отступы, например). Этот класс расширяется в файле компонентов, там в него добавляются стили для придания нужного внешнего вида. Эти связи между объектами мы должны обозначить с помощью указания на наследование стилей.

Например, в файле с главным классами (объектами):

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

.btn {}

В файле с дочерними классами:

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

.btn--positive {}

.btn--negative {}

Такое комментирование кода не потребует от разработчика больших усилий, и благодаря этим комментариям те, кому придется работать с вашим кодом, легко смогут разобраться в связях между классами.

Низкоуровневые комментарии

Часто нам требуется прокомментировать определенную строку кода с объявлением какого-либо свойства. Для этого мы используем сноски. По ссылке можно увидеть пример более сложного комментирования кода шапки сайта, о которой говорилось выше. Такой способ комментирования позволяет нам держать всю документацию в одном месте, и затем всего лишь ссылаться на нужное место в документации, вместо того, чтобы писать длинный комментарий прямо в коде.

Препроцессоры и комментирование

Во многих, если не во всех препроцессорах есть возможность добавлять комментарии, которые при компиляции не будут выводиться в итоговый файл стилей. Примите за правило использовать такие комментарии для кода, который также не будет скомпилирован. Для кода, который будет выведен в итоговый файл, используйте обычные комментарии.

Так правильно:

// 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] */
}

В этом примере мы задокументировали переменные (которые не будут скомпилированы) с помощью комментариев препроцессора, а для обычного кода мы применили стандартный способ комментирования. Такой способ гарантирует нам то, что в скомпилированных CSS-файлах будет только релевантная и нужная для нас информация.

Удаление комментариев

Следует сказать о том, что при использовании кода в продакшене все комментарии должны быть удалены, а сам CSS должен быть минифицирован перед деплоем.

Предыдущая часть: CSS GuideLines, часть 1.Синтаксис и форматирование