Skip to content

Code style

Jump to bottom
Dmitry Lutsik edited this page Dec 25, 2013 · 28 revisions

JS

HTML/CSS

Определения

Данные соглашения - набор правил разной степени обязательности исполнения. Используется три степени:

  • обязательно - нарушение правила не имеет смысла либо полностью запрещено. Нарушение должно обсуждаться заранее с командой;
  • должно - нарушение правила возможно при достаточном обосновании. Нарушение можно обсудить постфактум или оставить комментарий в коде;
  • рекомендуется - при прочих равных лучше использовать рекомендованный вариант.

Соглашения являются расширением методологии БЭМ, поэтому используются следующие термины:

  • блок - синоним понятий "плагин", "модуль" - неразрывная независимая часть ветки DOM дерева (или ветка целиком), и связанных с ней CSS правил, которая может быть переиспользована на любом проекте, в любом контексте. Блоком так же называется корневой тег такой структуры;
  • элемент - структурная единица блока. Элемент всегда принадлежит одной копии блока. Элемент не имеет смысла вне блока. Элемент не может принадлежать одновременно нескольким блокам, или нескольким копиям одного блока. При движении от элемента вверх по DOM дереву можно встретить любое число других элементов того же блока, либо сам блок. Нельзя встретить элементы других блоков или другие блоки;
  • модификатор - синоним понятия "состояние". Модификатор реализует наследование блоков - когда нам нужен второй блок, очень похожий на первый. Модификатор всегда относится к какому-то конкретному блоку или элементу. У любого блока и элемента может быть несколько модификаторов, по несколько значений у каждого.

Область применения

Данное соглашение применяется для вновь создаваемых блоков (плагинов). Сюда относится замена блока при рефакторинге. Соглашение имеет слабое влияние при небольших работах со старым кодом, а также при переиспользовании сторонних плагинов.

HTML

  • верстка должна быть валидным html5 кодом;
  • код должен быть максимально семантичным;
  • код должен быть в нижнем регистре;
  • рекомендуется не указывать типы для тегов script и link;
  • рекомендуется пропускать строку перед блоками, списками, таблицами и т.д.;
  • должны использоваться двойные кавычки в атрибутах HTML.

Рекомендуется использовать теги html5

  • article - выделение смысловой самостоятельной единицы (обычно блока);
  • address - тег для адреса;
  • aside - тег для сопутствующей информации, например "конкуренты";
  • time - тег для любого времени или даты;
  • header и footer для явно выраженной шапки и футера блока, если такие есть;
  • а также: summary, nav и другие.

Существующие теги и их назначение: http://www.w3.org/TR/html-markup/elements.html#elements

  • обязательно используются атрибуты schema.org;
  • не желательно использовать "табличные" теги: table, tr, td, tbody (кроме как по их прямому назначению - для отображения таблиц);
  • запрещено использование устаревших тегов: font, blink и прочее;
  • у каждого тега, который будет иметь визуальное представление на странице, должен быть CSS класс (полное покрытие тегов классами).

Структура

  • должна использоваться методология БЭМ;
  • любая визуальная HTML нода должна быть покрыта CSS классом;
  • Структура HTML должна быть семантичной и минимально зависеть от дизайна. Иными словами, по HTML коду должно быть всё понятно о содержимом страницы, но ничего не понятно о её дизайне.

Плохо:

<div class="outer-wrapper">
    <div class="inner-wrapper">
        <div class="right clerafix">Какой-то <span class="red">текст</span></div>
    </div>
</div>

Хорошо:

<article class="dg-card dg-card_type_org dg-card_spec_edu" itemscope itemtype="http://schema.org/EducationalOrganization">
    <header class="dg-card__header">
        <h1 class="dg-card__name" itemprop="name">Школа №176</h1>
    </header>
    <address class="dg-card__address" itemprop="streetAddress">Красный проспект, д. 348</address>
</article>

Приветствуется минимизация DOM дерева (исключение различных оберток, оболочек, разделителей, однопиксельных gif-файлов и т.п.).

Общий пример

<div class="dg-board">
    <div class="dg-board__list">
        <div class="dg-filters">...</div>
        <article class="dg-card" itemscope itemtype="http://schema.org/EducationalOrganization">
            <header class="dg-card__header">
                <h1 class="dg-card__name" itemprop="name">Школа №176</h1>
            </header>
            <address class="dg-card__address" itemprop="streetAddress">Красный проспект, д. 348</address>
        </article>
        <article class="dg-card">...</article>
        <article class="dg-card">...</article>
    </div>
</div>

CSS

Именование классов

  • обязательно используется методология БЭМ для именования всех CSS классов;
  • для блоков должен использоваться префикс .dg-, например: .dg-fullscreen;
  • любой CSS класс должен начинаться с имени блока;
  • любой класс по своему предназначению и правилам составления имени должен быть блоком, элементом, или модификатором;
  • модификатор обязан иметь четкое описание-комментарий;
  • запрещено использовать в имени блока любые символы, кроме a-z, 0-9 и "-", а в качестве первого символа любые, кроме a-z. То же касается составных частей элементов и модификаторов;
  • должны использоваться одинарные кавычки;
  • должны использоваться короткие 16-тиричные числа, когда это возможно (#ffffff -> #fff);
  • рекомендуется использовать сокращенные названия свойств CSS;
  • не рекомендуется использовать нули перед точкой в дробных числах, единицы измерения после нулевых значений.

Примеры классов блоков: .dg-search, .dg-popup, .dg-card, .dg-firm-list.

  • имя любого элемента обязательно имеет префикс .block__, где "block" - имя блока, которому принадлежит этот элемент.

Примеры классов элементов: .dg-card__name, .dg-search__query, .dg-popup__close.

  • имя модификатора обязательно имеет префикс block_ или block__elem_ и состоит из двух частей: имя модификатора и значение модификатора.

Примеры классов модификаторов:

  • .dg-card_type_firm - тип карточки "фирма";
  • .dg-search_mode_metro - режим строки поиска "метро";
  • .dg-popup_state_hidden - состояние коллаута "скрыт";
  • .dg-board__list_state_minimized - состояние элемента "список" равно "свёрнут".

Модификаторы:

  • любой модификатор обязательно относится только к какому-то конкретному элементу или блоку;
  • разрешено использовать несколько разных модификаторов блока или элемента одновременно (например .dg-card_state_visible и .dg-card_type_building);
  • запрещено использовать несколько разных значений одного модификатора или элемента одновременно (например .dg-card_state_hidden и .dg-card_state_visible).

Селекторы

  • селектор должен состоять только из одного имени класса;
  • селекторы по тегам и id крайне не желательны;
  • одно состояние одного селектора должно встречаться в CSS 0 или 1 раз;
  • селекторы через запятую не желательны. Если такая необходимость сильно выражена, то стоит подумать о создании нового элемента с общими стилями, и его примешиванию к уже существующим в HTML коде;
  • классы должны быть сгруппированы вокруг своего блока в порядке: блок, элементы, модификаторы блока. То есть, в потоке CSS одним выделением можно выделить все стили блока и его элементов;
  • состояния класса должны быть также сгруппированы: класс, его псевдоклассы, его псевдоэлементы;
  • модификаторы блока должны быть сгруппированы по названию модификатора и по его значениям;
  • псевдоэлементы before и after должны отделяться от селектора одинарным двоеточием.

Свойства

  • !important не должен использоваться;
  • IE хаки не должны использоваться в основных стилях;
  • наличие невалидного CSS должно быть строго обосновано. Используем CSS валидатор;
  • любое неочевидное свойство или значение должно поясняться /* комментарием */ на английском языке.
Clone this wiki locally