Skip to content

Latest commit

 

History

History

ru-RU

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Принципы написания однородного CSS-кода

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

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

«Принципы написания однородного CSS» на английском языке (Original)

Содержание

  1. Общие принципы
  2. Отступы
  3. Комментарии
  4. Форматирование
  5. Именование
  6. Практический пример
  7. Организация кода
  8. Сборка и развёртывание

Благодарности

1. Общие принципы

«Вы сослужите проекту хорошую службу, если будете осознавать, что написание кода только для себя — Плохая Идея™. Если тысячи людей используют ваш код, то пишите его максимально ясным и не делайте что-то только потому, что спецификация языка допускает это». — Idan Gazit

  • Весь код в любом проекте должен выглядеть так, будто его создал один человек, вне зависимости от того, сколько людей на самом деле принимали участие.
  • Строго соблюдайте соглашения.
  • В сомнительных случаях используйте общепринятый подход.

2. Отступы

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

  • Никогда не смешивайте пробелы и табуляцию.
  • Между табуляцией и мягкими отступами (пробелы вместо табуляции) выберите что-то одно. Придерживайтесь своего выбора, не делая исключений. (Предпочтение: пробелы)
  • Если вы используете пробелы, определитесь с количеством символов, соответствующим одному уровню отступа. (Предпочтение: 4 пробела)

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

3. Комментарии

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

Стиль комментариев должен быть простым и однородным для всего проекта.

  • Помещайте комментарий на строке перед комментируемым фрагментом кода.
  • Избегайте добавления комментариев в конец строки.
  • Установите обоснованную максимальную длину строки, например, 80 символов.
  • Свободно используйте комментарии для оформления разделов внутри CSS-файла.
  • Начинайте предложения с заглавной буквы, в конце ставьте точку, а также используйте однородные отступы.

Совет: настройте в редакторе кода горячие клавиши для быстрого набора шаблонов комментирования.

Пример для CSS:

/* ==========================================================================
   Блок комментариев для раздела
   ========================================================================== */

/* Блок комментариев для подраздела
   ========================================================================== */

/*
 * Блок комментариев для группы правил.
 * Хорошо подходит для подробных пояснений и документации.
 */

/* Обычный комментарий */

Пример для SCSS:

// ==========================================================================
// Блок комментариев для раздела
// ==========================================================================

// Блок комментариев для подраздела
// ==========================================================================

//
// Блок комментариев для группы правил.
// Хорошо подходит для подробных пояснений и документации.
//

// Обычный комментарий

4. Форматирование

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

  1. При создании правила для нескольких селекторов помещайте каждый селектор на отдельной строке.
  2. Перед открывающей скобкой ставьте один пробел.
  3. Внутри блока объявлений помещайте каждое объявление на отдельной строке.
  4. Добавляйте один уровень отступов перед каждым объявлением.
  5. Ставьте пробел после двоеточия внутри объявления.
  6. Всегда ставьте точку с запятой после последнего объявления в блоке.
  7. Ставьте закрывающую скобку на одной вертикальной линии с первым символом в селекторе.
  8. Разделяйте правила пустой строкой.
.selector-1,
.selector-2,
.selector-3 {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    display: block;
    color: #333;
    background: #fff;
}

Порядок объявлений

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

.selector {
    position: relative;
    display: block;
    width: 50%;
    height: 100px;
    padding: 10px;
    border: 0;
    margin: 10px;
    color: #fff
    background: #000;
}

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

Исключения и небольшие отклонения

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

.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }

Длинные значения свойств, разделяемые запятыми — как, например, набор градиентов или теней — могут быть помещены на отдельной строке каждое, чтобы повысить читабельность кода и сообщений в системе управления версиями. Формат записи может слегка различаться, один из вариантов приведён ниже.

.selector {
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
}

Прочее

  • Пишите шестнадцатеричные значения в нижнем регистре, например, #aaa.
  • Последовательно используйте либо одинарные, либо двойные кавычки. Я предпочитаю двойные, к примеру, content: "".
  • Всегда берите в кавычки значения атрибутов внутри селектора, например, input[type="checkbox"].
  • Везде, где возможно, опускайте единицы измерения при нулевом значении, например, margin: 0.

Препроцессоры: дополнительные соглашения

Разные препроцессоры CSS имеют разный набор возможностей и различный синтаксис. Ваши соглашения должны быть дополнены, чтобы отражать особенности использования конкретного препроцессора. Следующий набор правил относится к Sass.

  • Ограничивайте вложенность одним уровнем. Пересмотрите все правила, в которых больше двух уровней вложенности. Это позволит избегать чрезмерной специфичности правил.
  • Избегайте большого числа вложенных правил. Оформляйте их отдельно, когда их становится трудно читать. Предпочтительно ограничивать длину вложенных правил 20 строками.
  • Всегда помещайте оператор @extend в первой строке блока объявлений.
  • По возможности группируйте операторы @include в начале блока объявлений, сразу после @extend.
  • Подумайте над добавлением префикса вида x- перед своими функциями. Это позволит избежать возможной путаницы между вашими функциями и стандартными функциями CSS, а также функциями из сторонних библиотек.
.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // прочие объявления
}

5. Именование

Вы не компилятор и не компрессор кода, поэтому ведите себя соответственно.

Используйте понятные и осмысленные имена для классов в HTML. Выберите ясный и последовательный шаблон именования, который будет удобен как для HTML, так и для CSS.

/* Пример кода с плохими именами */

.s-scr {
    overflow: auto;
}

.cb {
    background: #000;
}

/* Пример лучшего подхода к именованию */

.is-scrollable {
    overflow: auto;
}

.column-body {
    background: #000;
}

6. Практический пример

Пример использования нескольких соглашений.

/* ==========================================================================
   Макет сетки
   ========================================================================== */

/*
 * HTML для примера:
 *
 * <div class="grid">
 *     <div class="cell cell-5"></div>
 *     <div class="cell cell-5"></div>
 * </div>
 */

.grid {
    overflow: visible;
    height: 100%;
    /* Предотвращаем перенос строчных блоков на новую строку */
    white-space: nowrap;
    /* Убираем пробелы между ячейками сетки */
    font-size: 0;
}

.cell {
    box-sizing: border-box;
    position: relative;
    overflow: hidden;
    width: 20%;
    height: 100%;
    /* Задаём отступы внутри ячеек */
    padding: 0 10px;
    border: 2px solid #333;
    vertical-align: top;
    /* Восстанавливаем поведение по умолчанию */
    white-space: normal;
    /* Восстанавливаем размер шрифта */
    font-size: 16px;
}

/* Состояния ячеек */

.cell.is-animating {
    background-color: #fffdec;
}

/* Размеры ячеек
   ========================================================================== */

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }

/* Модификаторы для ячеек
   ========================================================================== */

.cell--detail,
.cell--important {
    border-width: 4px;
}

7. Организация кода

Организация кода — важная часть любого проекта на CSS и ключевой элемент в большом проекте.

  • Логически отделяйте различные части кода.
  • Используйте отдельные файлы (объединяемые на этапе сборки), чтобы разделить код обособленных компонентов.
  • При использовании препроцессора оформляйте часто используемый код в переменные, например, для типографики, цветов и т.д.

8. Сборка и развёртывание

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

Благодарности

Спасибо всем, кто внёс вклад в проект idiomatic.js. Это мой источник вдохновения, цитат и общих рекомендаций.