gistfile1.md

Стандарт по написанию кода в CSSSR

Стандарты для разработки гибкого, надёжного и поддерживаемого кода на HTML и CSS.

Оглавление

• Общее положение

• HTML

  • Синтаксис
  • HTML5 doctype
  • Атрибут языка
  • Режим совместимости Internet Explorer
  • Кодировка символов
  • Подключение CSS и JavaScript
  • Относительные и абсолютные пути до ресурсов
  • Название файлов
  • Порядок атрибутов
  • Логические атрибуты
  • Элементы и атрибуты элементов форм
  • Ссылки с протоколами
  • Сокращение разметки
  • Изображения
  • Взаимодействие HTML и JavaScript
  • Комментарии

• CSS

  • CSS синтаксис
  • Порядок объявления
  • Не используйте @import
  • Место для media query
  • Свойства с префиксами
  • Правила с одиночными объявлениями
  • Сокращенная запись
  • Stylus
  • Комментарии
  • БЭМ и именование классов
  • Селекторы
  • Организация кода

Общее положение

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

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

HTML

Старайтесь соблюдать стандарты HTML и семантику, но не за счет практичности. Используйте меньшее количество разметки с наименьшим числом тонкостей, когда это возможно.

Синтаксис

• Для вложенных элементов отступы должны быть только табами. В любом редакторе можно задать индивидуальный размер. Оптимальный размер - 4.
  В этом примере ∙∙ - два пробела, а ―――― - один отступ с табуляцией.

<!-- Плохо -->
<div class="block">
∙∙<div class="block__element">CSSSR</div>
</div>

<!-- Хорошо -->
<div class="block">
――――<div class="block__element">CSSSR</div>
</div>

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

<!-- Плохо -->
<div class="block"><div class="block__element">CSSSR</div></div>

<!-- Хорошо -->
<div class="block">
  <div class="block__element">CSSSR</div>
</div>

• Группа однотипных блоков должна иметь два переноса.

<!-- Плохо -->
<div class="project">
  <div class="project__name">Lorem</div>
  <div class="project__desc">Lorem ipsum dolor sit amet, consectetur adipisicing elit.</div>
</div>
<div class="project">
  <div class="project__name">Ipsum.</div>
  <div class="project__desc">Lorem ipsum dolor sit amet, consectetur adipisicing elit.</div>
</div>

<!-- Хорошо-->
<div class="project">
  <div class="project__name">Lorem</div>
  <div class="project__desc">Lorem ipsum dolor sit amet, consectetur adipisicing elit.</div>
</div>

<div class="project">
  <div class="project__name">Ipsum.</div>
  <div class="project__desc">Lorem ipsum dolor sit amet, consectetur adipisicing elit.</div>
</div>

• Блочные элементы не должны находиться в строчных.

<!-- Плохо -->
<span>
  <div>:(</div>
</span>

<!-- Хорошо -->
<span>
  <span>:)</span>
</span>

• После закрывающихся тегов не должно быть лишних пробелов и/или табов. Для автоудаления можно настроить свой редактор кода. Для Sublime Text можно посмотреть в репе sputnik.

<!-- Плохо -->
<div class="block">∙
  <div class="block__element">CSSSR</div>∙∙∙∙
</div>――――――――

<!-- Хорошо -->
<div class="block">
  <div class="block__element">CSSSR</div>
</div>

• Названия тегов, атрибутов и значений свойств (кроме текстовых данных) должны быть в нижнем регистре.

<!-- Плохо -->
<INPUT TYPE="TEXT" VALUE="CSSSR">

<!-- Хорошо -->
<input type="text" value="CSSSR">

• Всегда используйте двойные кавычки "" для значений атрибутов.

<!-- Плохо -->
<div class=block>
  <div class=block__element>CSSSR</div>
</div>

<div class='block'>
  <div class='block__element'>CSSSR</div>
</div>

<!-- Хорошо -->
<div class="block">
  <div class="block__element">CSSSR</div>
</div>

• Не добавляйте слэш / в конец одиночного тега — в HTML5 он необязателен.

<!-- Плохо -->
<input type="text" value="CSSSR"/>

<!-- Хорошо -->
<input type="text" value="CSSSR">

• Не пропускайте необязательные закрывающие теги (например, </li>, </p> или </body>).

<!-- Плохо -->
<body>
  <p>Полезные инструменты
  <ul>
    <li>Grunt
    <li>Jade
    <li>Stylus
  </ul>


<!-- Хорошо -->
<body>
  <p>Полезные инструменты</p>
  <ul>
    <li>Grunt</li>
    <li>Jade</li>
    <li>Stylus</li>
  </ul>
</body>

HTML5 doctype

Укажите в начале каждой вашей HTML-страницы этот тип документа. Это заставит браузер работать в режиме соответствия стандартам, что обеспечит единообразное отображение ваших страниц в разных браузерах.

<!DOCTYPE html>
<html>
	<head>
	  <!-- ... -->
	</head>
	<body>
	  <!-- ... -->
	</body>
</html>

Атрибут языка

Из спецификации HTML5:

Для указания языка документа авторам рекомендуется прописывать атрибут языка в корневом элементе HTML. Это поможет инструментам синтеза речи определить какое произношение использовать, а инструментам перевода - какие правила, и так далее.

<html lang="ru">
	<!-- ... -->
</html>

Подробнее познакомиться с атрибутом lang можно в спецификации.

Список кодов различных языков на Sitepoint.

Режим совместимости Internet Explorer

IE поддерживает использование специального <meta>-тега, который указывает в режиме совместимости с какой версией IE следует отрендерить страницу. Если обстоятельства не требуют какой-то специальной версии IE, то самым правильным будет заставить браузер использовать режим самой последней версии (edge mode).

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Если сайт будет находиться на собственном хостинге, то следует убрать этот meta-тег и настроить хостинг для определения IE и добавления специальных заголовков.

Для получения дополнительной информации можно ознакомиться с обсуждением на Stack Overflow.

Кодировка символов

Явно объявив кодировку символов, вы быстро и легко обеспечите правильное отображение вашего контента. При этом, вы сможете избежать использования символьных сущностей в вашем HTML-коде, при условии, что их кодировка совпадает с кодировкой документа (как правило, utf-8).

<head>
	<meta charset="utf-8">
</head>

Подключение CSS и JavaScript

Все стили и скрипты должны быть только в отдельных файлах. Встроенных и внедрённых в тег стилей (в атрибуте style) не должно быть.

Согласно спецификации HTML5, при подключении CSS и JavaScript файлов не требуется указание атрибута type, так как text/css и text/javascript являются значениями по умолчанию.

<!-- Внешний CSS -->
<link rel="stylesheet" href="styles/main.css">

<!-- CSS внутри документа, внедрять в страницу не нужно -->
<style>
	/* ... */
</style>

<!-- Внешний JavaScript -->
<script src="scripts/main.js"></script>

<!-- JavaScript внутри документа, внедрять в страницу не нужно -->
<script>
	console.log('CSSSR');
</script>

Ссылки на спецификацию HTML5:

• Использование тега link
• Использование тега style
• Использование тега script

Абсолютные и относительные пути к ресурсам

По умолчанию пути до ресурсов должны быть относительного текущего расположения страницы для просмотра на GitHub Pages.

Относительно корня или абсолютные пути можно использовать в некоторых случаях:

• Для страниц сайта, находящихся в поддиректории (обычно на хостинге CSSSR или заказчика).
• В JavaScript, например, для указания изображения метки на Яндекс.Картах или Google Maps.

Подробнее можно почитать на htmlbook.ru.

Название файлов

Называйте файлы страниц по-английски без ошибок, не используйте кириллицу, транслит и комбинацию транслита и английского.

Само название должно отражать содержимое файла.

Плохо:

Главная страница.html
Stranica novostey.html
01_about-NEW!!!.html
page-kontakti.html

Хорошо:

main.html
news.html
about.html
contacts.html

Порядок атрибутов

Для удобства чтения HTML-атрибуты должны быть указаны именно в этом порядке:

• class
• id, name
• data-*
• src, for, type, href
• title, alt
• aria-*, role

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

<a class="link" id="toggle" data-modal="toggle" href="javascript:void(0);">Меню</a>

<input class="input-text" type="text">

<img class="logo" src="images/logo.png" alt="CSSSR">

Логические атрибуты

Логические атрибуты одни из тех, которые не требуют объявленного значения. XHTML требует от вас задать значение, но в HTML5 нет такого требования.

За подробной информацией обратимся к разделу о логических атрибутах на WhatWG:

Наличие логического атрибута у элемента говорит об истинном его значении, а отсутствие атрибута — о ложном.

Если вы должны указать значение атрибута, но вам это не нужно, следуйте этой рекомендации от WhatWG:

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

Если коротко, то не указывайте значение логическому атрибуту.

<!-- Плохо -->
<input class="input-text" type="text" disabled="disabled">

<input class="input-checkbox" type="checkbox" value="on" checked="checked">

<select class="select">
	<option value="0" selected="selected">Grunt</option>
	<option value="1">Jade</option>
	<option value="2">Stylus</option>
</select>

<!-- Хорошо -->
<input class="input-text" type="text" disabled>

<input class="input-checkbox" type="checkbox" value="on" checked>

<select class="select">
	<option value="0" selected>Grunt</option>
	<option value="1">Jade</option>
	<option value="2">Stylus</option>
</select>

Элементы и атрибуты элементов форм

• Форма должна иметь атрибуты:
  • action - для указания адреса отправки данных.
  • method - метод передачи данных, обычно в значении указывается post.

<!-- Плохо -->
<form>
  <!-- ... -->
  <button type="submit">Подать заявку</button>
</form>

<!-- Хорошо -->
<form action="send.php" method="post">
  <!-- ... -->
  <button type="submit">Подать заявку</button>
</form>

• Кнопки подтверждения формы логично должны быть кнопками с атрибутом type="submit", а не ссылками, строчными или блочными элементами.

<!-- Плохо -->
<form action="send.php" method="post">
  <!-- ... -->
  <a href="send.php">Подать заявку</a>
</form>

<!-- Хорошо -->
<form action="send.php" method="post">
  <!-- ... -->
  <button type="submit">Подать заявку</button>
</form>

• Если списки с выбором одного или нескольких значений генерируются с помощью JavaScript, то выбранное значение должно отмечаться в дочернем элементе <option value="1" selected>Jade</option> или , если тег select не используется, то сохраняться в теге <input type="text">.

• Элементы формы должны иметь атрибуты:

  • name и value - для ключа и значения.
  • for и id - для связи надписи и элемента, при клике на надпись элемент будет фокусироваться.

<label for="skype">Skype</label>
<input id="skype" name="skype" value="csssr.ru">

Ссылки и протоколы

• Для ссылок без адреса вместо # вставлять javascript:void(0);, чтобы страницу не скроллило вверх.

<!-- Плохо -->
<a href="#">Портфолио CSSSR</a>

<!-- Хорошо -->
<a href="javascript:void(0);">Портфолио CSSSR</a>

• Для внешних ссылок нужно добавлять атрибуты target="_blank" для открытия в новой вкладке и rel="nofollow" для запрета отслеживания.

<!-- Плохо -->
Мы пользуемся поисковой системой <a href="http://yandex.ru/">Яндекс</a>.

<!-- Хорошо -->
Мы пользуемся поисковой системой <a href="http://yandex.ru/" target="_blank" rel="nofollow">Яндекс</a>.

• Телефоны, email-адреса и Skype-контакт должны быть ссылками:
  • tel:+79876543210 - для указания телефона, номер должен начинаться с плюса и состоять только из чисел без спецсимволов типа пробелов, круглых скобок или дефиса.
  • mailto:sales@csssr.com - для указания e-mail.
  • skype:csssr.ru?chat - для указания Skype-контакта.

<a href="tel:+79876543210">+7-987-654-32-10</a>
<a href="mailto:sales@csssr.com">Напишите нам на почту</a>
<a href="skype:csssr.ru?chat">Напишите нам в Skype</a>

Сокращение разметки

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

<!-- Неплохо -->
<span class="avatar">
	<img src="avatars/csssr.png" alt="CSSSR">
</span>

<!-- Лучше -->
<img class="avatar" src="avatars/csssr.png" alt="CSSSR">

Изображения

При размещении изображений следует учитывать то, чем они являются:

• Если изображение - стилевое оформление сайта, то реализуется в CSS фонах через свойство background. Например:

  • Фон сайта;
  • Паттерн;
  • Декоративные элементы;
  • И прочее.

• Используйте тег img для изображений:

  • Аватарок;
  • Продуктов в витрине;
  • Фотографий;
  • Любых изображений находящихся в контентной части:
    • Статьи;
    • Записи в блоге;
    • Комменатрия.

  Такие изображения должны быть отдельными файлами и находиться в папке images/temp/.

• В тегах img обязательно должен быть атрибут alt. Если изображение не меняет свой размер (не резиновое), то нужно его указать в атрибутах width и height.

<!-- Плохо -->
<img src="images/csssr.png">

<!-- Хорошо -->
<img src="images/csssr.png" alt="CSSSR">

<img src="images/csssr.png" alt="CSSSR" width="128" height="64">

Взаимодействие HTML и JavaScript

• Создание разметки с помощью JavaScript делает её менее производительной, сложной для поиска и редактирования. По возможности избегайте этого.

• В зависимости от поддерживаемых браузеров используйте CSS по максимуму (анимации, табы, псевдоэлементы), не используйте JavaScript.

• Если JavaScript изменяет вид страницы, обязательно делать это при помощи смены CSS-классов, а не путём правки атрибута style элемента.

• Если в форме элемент удаляется (скрывается), он должен удаляться и из DOM.

Комментирование кода

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

CSS

CSS синтаксис

• Табуляцию для отступов вместо пробелов. В любом редакторе кода размер можно настроить на своё усмотрение (например, размер табуляции 4).
  В этом примере ∙∙∙∙ - четыре пробела, а ―――― - один отступ с табуляцией.

/* Плохо */
.heading {
∙∙∙∙font-size: 32px;
}

/* Хорошо */
.heading {
――――font-size: 32px;
}

• Каждый селектор на отдельной строке.

/* Плохо */
.header, .main, .footer {
    margin-left: auto;
    margin-right: auto;
}

/* Хорошо */
.header,
.main,
.footer {
    margin-left: auto;
    margin-right: auto;
}

• 1 пробел перед {.

/* Плохо */
.heading{
    font-size: 32px;
}

/* Хорошо */
.heading {
    font-size: 32px;
}

• 1 перенос на новою строку перед }.

/* Плохо */
.heading {
    font-size: 32px;}

.heading {
    font-size: 32px;
    }

/* Хорошо */
.heading {
    font-size: 32px;
}

• 1 перенос на новою строку после } и между группами объявлений.

/* Плохо */
.heading {
    font-size: 32px;
}
.highlight {
    background-color: #f00;
}

/* Хорошо */
.heading {
    font-size: 32px;
}

.highlight {
    background-color: #f00;
}

• 1 пробел после :.

/* Плохо */
.heading {
    font-size:32px;
}

/* Хорошо */
.heading {
    font-size: 32px;
}

• Все объявления завершаются с ;.

/* Плохо */
.heading {
    font-size: 32px
}

/* Хорошо */
.heading {
    font-size: 32px;
}

• 1 пробел после запятых в значениях свойств.

/* Плохо */
.header {
    background-color: rgba(0,0,0,.5);
}

/* Хорошо */
.header {
    background-color: rgba(0, 0, 0, .5);
}

• Не добавляйте начальный ноль для значений.

/* Плохо */
.transparent {
    opacity: 0.5;
}

/* Хорошо */
.transparent {
    opacity: .5;
}

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

/* Плохо */
.white {
    background-color: #FFF;
}

/* Хорошо */
.white {
    background-color: #fff;
}

• Используйте короткие 16-ичные значения.

/* Плохо */
.highlight {
    color: #ffffff;
    background-color: #0088ff;
}

/* Хорошо */
.highlight {
    color: #fff;
    background-color: #08f;
}

• " для значений атрибутов внутри селектора.

/* Плохо */
input[type=text] {
    /* ... */
}

/* Хорошо */
input[type="text"] {
    /* ... */
}

• Опускайте единицы измерения при нулевом значении.

/* Плохо */
.header {
    margin-top: 0px;
}

/* Хорошо */
.header {
    margin-top: 0;
}

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

Объявления логически связанных свойств должны быть сгруппированы в следующем порядке:

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

Полный список порядка свойст можно посмотреть в конфигурации CSScomb.

Небольшой пример:

.declaration-order {
    /* Позиционирование */
    position: absolute;
    z-index: 100;
    top: 0;
    right: 0;
    left: 0;
    bottom: 0;
    
    /* Расположение */
    margin-top: 20px;
    margin-left: auto;
    margin-right: auto;
    padding: 8px 16px;

    /* Блочная модель */
    display: block;
    float: left;
    width: 100px;
    height: 100px;
    
    /* Типографика */
    font-family: 'Helvetica Neue', sans-serif
    font-size: 14px;
    line-height: 24px;
    text-align: center;
    
    /* Отображение */
    color: #333;
    background-color: #f5f5f5;
    border: 1px solid #e5e5e5;
    border-radius: 3px;
    opacity: 1;
    
    /* Прочее */
    transition: .25s ease-out;
    transform: scale(.75);
}

Не используйте @import

Место для media query

Свойства с префиксами

Правила с одиночными объявлениями

Сокращенная запись

Stylus

Комментарии

БЭМ и именование классов

Селекторы

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