WordPress.org

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Стандарты кодирования CSS

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

Внутри основной таблицы стилей часто будут обнаруживаться несоответствия. Мы работаем над решением этих проблем и прилагаем максимум усилий, чтобы патчи с этого момента соответствовали стандартам кодирования CSS. Подробная информация по данной теме и о вкладе в UI/front-end разработку будет изложена в виде отдельного набора инструкций.

Структура

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

  • Используйте табуляции, а не пробелы для отступа у каждого свойства.
  • Добавляйте две пустые строки между разделами и одну пустую строку между блоками в разделе.
  • Каждый селектор должен находиться на отдельной строке, заканчивающейся либо запятой, либо открывающей фигурной скобкой. Каждая пара свойство-значение должна быть на отдельной строке, с отступом в одну табуляцию и с точкой с запятой в конце. Закрывающая фигурная скобка должна быть на том же уровне слева, что и открывающий селектор.

Правильно:

#selector-1,
#selector-2,
#selector-3 {
	background: #fff;
	color: #000;
}

Неправильно:

#selector-1, #selector-2, #selector-3 {
	background: #fff;
	color: #000;
	}
#selector-1 { background: #fff; color: #000; }

Селекторы

Со специфичностью связано больше ответственности. Общие селекторы позволяют нам быть эффективными, но могут иметь отрицательные последствия, если не выполнено тщательное тестирование. Более специфичные селекторы могут сохранить нам время, но быстро приведут к сумбуру в таблице стилей. Опыт - лучший помощник для нахождения правильного баланса между общими стилями и шаблоном DOM.

  • Для имен селекторов, используйте слова в нижнем регистре, разделенные дефисами. Избегайте CamelCase-нотации и знаков подчеркивания.
  • Используйте удобочитаемые селекторы, описывающие элементы, к которым они применяются.
  • Для значений атрибутов селекторов используйте двойные кавычки.
  • Воздерживайтесь от использования слишком детальных селекторов, вместо div.container можно просто указать .container.

Правильно:

#comment-form {
    margin: 1em 0;
}
 
input[type="text"] {
    line-height: 1.1;
}

Неправильно:

#commentForm { /* Избегайте CamelCase-нотации. */
    margin: 0;
}
 
#comment_form { /* Избегайте знаков подчеркивания. */
    margin: 0;
}
 
div#comment_form { /* Избегайте излишней детализации. */
    margin: 0;
}
 
#c1-xr { /* Что значит c1-xr?! Используйте осмысленное имя. */
    margin: 0;
}
 
input[type=text] { /* Должно быть [type="text"] */
    line-height: 110% /* Вдвойне неправильно */
}

Свойства

Также как и в случае с селекторами, слишком детализированные свойства ухудшают гибкость дизайна. Меньше означает больше. Убедитесь, что вы не повторяете стили и не вводите фиксированные размеры (когда резиновое решение является более приемлемым).

  • За свойством должны идти двоеточие и пробел.
  • Все свойства и значения должны быть в нижнем регистре, за исключением названий шрифтов и нестандартных свойств разработчиков.
  • Используйте шестнадцатеричные коды для цветов или rgba(), если нужна прозрачность. Избегайте формата RGB и прописных букв и сокращайте значения, если это возможно: #fff вместо #FFFFFF.
  • Максимально используйте универсальные свойства (за исключением случаев, когда это приводит к переопределению стилей) для фона, границ, шрифтов, стилей списка, полей и отступов. (См. краткий справочник CSS Shorthand).

Упорядочивание свойств

“Группируйте понравившиеся свойства вместе, особенно если у вас их много.”
 - Nacin

Прежде всего, выберите то, что имеет смысл для вас и является в некотором роде семантическим. Случайный порядок - это хаос, а не поэзия. Для ядра WordPress наш выбор - логическое или групповое упорядочивание, при котором свойства сгруппированы по смыслу и упорядочены определенным образом в рамках этих групп. Свойства в пределах группы упорядочиваются так, чтобы создать переходы между секциями, например фон непосредственно перед цветом шрифта. Основная схема упорядочивания:

  • Отображение
  • Позиционирование
  • Блочная модель
  • Цвета и шрифты
  • Другие

Вещи, которые пока не используются в ядре, такие как CSS3-анимации, могут не иметь предписанного места, но скорее всего вписались бы в приведенную выше схему каким-то логическим способом. Просто поскольку CSS развивается, наши стандарты будут меняться вместе с ним.

Top/Right/Bottom/Left (TRBL/trouble) - порядок для любых соответствующих свойств (например, margin). Свойства углов (например, border-radius-*-*) должны идти в порядке: top-left, top-right, bottom-right, bottom-left. Эти правила следуют из того, как указываются универсальные свойства.

Пример:

#overlay {
    position: absolute;
    z-index: 1;
    padding: 10px;
    background: #fff;
    color: #777;
}

Другой метод, который часто используется, в том числе и группой Automattic/WordPress.com Themes, состоит в упорядочивании свойств по алфавиту, с некоторыми исключениями или без них.

Пример:

#overlay {
    background: #fff;
    color: #777;
    padding: 10px;
    position: absolute;
    z-index: 1;
}

Префиксы разработчиков

Мы используем grunt-autoprefixer в качестве инструмента предварительной обработки, чтобы легко управлять необходимыми для браузеров префиксами, таким образом делая большую часть этой спорной работы. Для тех, кому интересно, каким должен быть выход без использования Grunt, префиксы разработчиков должны идти от длинных (-webkit-) к коротким (без префикса). Остальные правила упорядочивания стандартны.

.sample-output {
    -webkit-box-shadow: inset 0 0 1px 1px #eee;
    -moz-box-shadow: inset 0 0 1px 1px #eee;
    box-shadow: inset 0 0 1px 1px #eee;
}

Значения

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

  • Пробел перед значением, после двоеточия.
  • Не ставьте лишних пробелов около скобок.
  • Всегда ставьте конечную точку с запятой.
  • Используйте двойные кавычки, а не одинарные, и только при необходимости, например, если имя шрифта содержит пробелы.
  • Нулевые значения не должны иметь единиц, за исключением случаев, когда они необходимы, например с transition-duration.
  • Высота строки должна быть безразмерной, за исключением случаев, когда она должна быть определена как конкретное значение в пикселях. Это не просто соглашение о стиле, но об этом стоит здесь упомянуть. Дополнительная информация: http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/
  • Используйте ведущий нуль для десятичных значений, в том числе в rgba().
  • Несколько разделенных запятыми значений для одного свойства должны быть разделены либо пробелом, либо переводом строки, в том числе в rgba(). Переводы строк должны быть использованы для длинных составных значений, таких как сокращенные свойства, подобные box-shadow или text-shadow. Каждое последующее значение после первого должно располагаться на новой строке, выровненное по левому краю с предыдущим значением.

Правильно:

.class { /* Правильное использование кавычек */
    background-image: url(images/bg.png);
    font-family: "Helvetica Neue", sans-serif;
}
 
.class { /* Правильное использование нулевых значений */
    font-family: Georgia, serif;
    text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.5),
                 0 1px 0 #fff;
}

Неправильно:

.class { /* Избегайте пропускать конечную точку с запятой  */
    background:#fff
}
 
.class { /* Избегайте добавлять единицу измерения к нулевым значениям */
    margin: 0px 0px 20px 0px;
}

Указание типа носителя

Использование команды @media позволяет изящно подстраивать дерево DOM для различных размеров экрана. При добавлении команды @media обязательно проверьте результат выше и ниже пограничного размера, который вы используете.

  • Вообще, желательно размещать команды @media, сгруппированные по типу носителя, в нижней части таблицы стилей.
  • Исключение составляет файл wp-admin.css в ядре, так как он очень большой, и каждый раздел по существу представляет собой отдельную таблицу стилей. Поэтому команды @media следует добавлять в конец соответствующих разделов.
  • Наборы стилевых правил должны быть сдвинуты на один уровень внутрь.

Пример:

@media all and (max-width: 699px) and (min-width: 520px) {
 
        /* Your selectors */
}

Комментарии

  • Комментируйте и комментируйте подробно. Если есть опасения по поводу размера файла, используйте сжатые файлы и постоянную SCRIPT_DEBUG. Длинные комментарии должны вручную разбиваться на строки длиной в 80 символов.
  • Для больших стилевых файлов должно использоваться оглавление, особенно если файл содержит большое количество разделов. Используйте индексацию (1.0, 1.1, 2.0 и т.д.) для поиска и перемещения по стилевому файлу.
  • Комментарии должны быть отформатированы в соответствии со стандартом PHPDoc. CSSDoc не обязателен к использованию, но некоторые его аспекты могут быть приняты с течением времени. Заголовки разделов/подразделов должны иметь переводы строк до и после них. Inline-комментарии не должны иметь переводов строки, отделяющих комментарий от элемента, к которому он относится.

Заголовки разделов и подразделов:

/**
* #.# Заголовок раздела
*
* Описание раздела, имеет ли он команды media и т.д. 
*/
 
.selector {
    float: left;
}

Inline-комментарии:

/* Комментарий, описывающий селектор */
 
.another-selector {
    position: absolute;
    top: 0 !important; /* Объяснение, почему используется !important */
}

Практические рекомендации

Таблицы стилей, как правило, получаются длинные. Фокус медленно теряется, в то время как цели начинают повторяться и перекрываться. Написание умного кода с самого начала помогает сохранить общую канву и не потерять гибкость при изменениях.

  • Если вы пытаетесь решить проблему, попробуйте сначала удалить код, прежде чем добавлять дополнительный.
  • Магические числа - несчастливые. Это числа, которые используются для быстрого исправления на разовой основе. Пример: .box { margin-top: 37px }.
  • DOM будет меняться с течением времени. Определяйте стили непосредственно для элемента, не используя родителей. Пример: используйте .highlight, где выбирается сам элемент, а не .highlight a (где селектор начинается с родителя).
  • Правильно используйте свойство height. Оно должно использоваться, когда вы включаете внешние элементы (например, изображения). В противном случае используйте свойство line-height для большей гибкости.
  • Не переопределяйте установленные по умолчанию комбинации свойство-значение (например, display: block; для блочных элементов).

Связанные ссылки