Стиль кода Академии HTML

github.com/htmlacademy/codeguide

Оглавление

HTML

Синтаксис

  • Для отступов у вложенных элементов используются два пробела. Для правильного форматирования используйте файл .editorconfig в вашем редакторе.
  • Теги и их атрибуты пишутся строчными буквами. Для значений атрибутов всегда используются двойные кавычки.
  • Необязательный закрывающий слеш у одиночных тегов (<img>, <br> и другие) не ставится.
  • Необязательные закрывающие теги (например, </li> или </body>) не пропускаются.
  • Для проверки HTML-кода используйте файл конфигурации .htmlhintrc для настройки валидатора HTMLHint.
<!DOCTYPE html>
<html lang="ru">
  <head>
    <meta charset="utf-8">
    <title>Страница о коте</title>
  </head>
  <body>
    <article class="post">
      <h1>Красивый кот</h1>
      <figure class="post-item">
        <img src="cat.jpg" alt="Изображение кота">
        <figcaption>Кот красив!</figcaption>
      </figure>
    </article>
  </body>
</html>

Валидность

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

HTML-доктайп

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

<!DOCTYPE html>
<html lang="ru">
  <head>…</head>
  <body>…</body>
</html>

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

Кодировка символов на странице всегда должна быть явно указана, чтобы обеспечить корректное отображение текста. Кодировка utf-8 предпочтительна.

<head>
  <meta charset="utf-8">
  <title>Заголовок страницы</title>
</head>

Подключение стилей

Стилевые файлы с помощью <link> подключаются внутри <head>. При этом атрибут type для тега <link> не указывается, так как его значение text/css устанавливается по умолчанию.

<!-- Хорошо: стилевой файл подключён в секции head -->
<!DOCTYPE html>
<html lang="ru">
  <head>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>…</body>
</html>

<!-- Плохо: стилевой файл подключён в секции body -->
<!DOCTYPE html>
<html lang="ru">
  <head>…</head>
  <body>
    <link rel="stylesheet" href="style.css">
  </body>
</html>

Подключение скриптов

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

При подключении скриптов в теге <script> атрибут type не указывается, так как его значение text/javascript устанавливается по умолчанию.

<!-- Хорошо: скрипт подключается перед </body> -->
<!DOCTYPE html>
<html lang="ru">
  <head>…</head>
  <body>
    <!-- Содержимое страницы -->
    <script src="app.js"></script>
  </body>
</html>

<!-- Плохо: скрипт подключается в секции <head> -->
<!DOCTYPE html>
<html lang="ru">
  <head>
    <script src="app.js"></script>
  </head>
  <body>…</body>
</html>

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

Атрибут класса у HTML-элементов пишется первым. Единообразное написание помогает легче считывать код и быстрее разбираться в назначении блоков по их классам.

Остальные атрибуты могут быть расставлены в любом порядке, но тоже единообразно для одинаковых элементов.

<a class="element element-big" id="element" href="/" data-name="element">Ссылка</a>

<input class="form-control" type="text" name="test">

<img class="pets-picture" src="cats.jpg" alt="Изображение котиков">

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

Для логических атрибутов (например, checked, disabled, required) значение не указывается, а сами атрибуты указываются последними и в единообразной последовательности во всём документе.

<!-- checked="checked" необязательно -->
<input type="checkbox" required checked>

<input type="text" disabled>

<select>
  <option value="1" selected>1</option>
</select>

Подписи полей ввода

Для улучшения взаимодействия пользователя с элементами форм, при нажатии на подпись поля, оно должно активироваться. Для этого элемент формы связывается с его описанием с помощью идентификатора и атрибута for тега <label>.

<!-- Хорошо: элемент формы radio связан с подписью через идентификатор -->
<input type="radio" id="choose">
<label for="choose">Радио кнопка</label>

<!-- Хорошо: элемент формы radio и подпись обёрнуты в label -->
<label>
  <input type="radio"> Радио кнопка
</label>

<!-- Плохо: подпись не связана с элементом формы -->
<input type="radio" id="choose"> Радио кнопка

Размеры картинок

Изображениям <img> должны быть явно заданы с помощью атрибута размеры в пикселях. В случае пикселей размерность не нужна.

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

<!-- Хорошо: размеры картинке заданы -->
<div class="logo-area">
  <img src="logo.png" alt="" width="300" height="150">
</div>

<!-- Плохо: размеры картинке заданы в px -->
<div class="logo-area">
  <img src="logo.png" alt="" width="300px" height="150px">
</div>

<!-- Плохо: размеры картинке не заданы -->
<div class="logo-area">
  <img src="logo.png" alt="">
</div>

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

Для элемента <html> в атрибуте lang должен указываться соответствующий язык документа. Это помогает инструментам синтеза речи определить, какое использовать произношение или системам перевода, какие использовать языковые правила.

<!DOCTYPE html>
<html lang="ru">
  <head>…</head>
  <body>…</body>
</html>

CSS

Синтаксис

  • После значения свойства обязательно ставится точка с запятой.
  • Для отступов внутри правил используются два пробела. Для правильного форматирования используйте файл .editorconfig в вашем редакторе.
  • Шестнадцатеричное значение цвета не сокращается, а пишется полностью из всех шести символов. Для записи используются строчные буквы. Например, #f5f5f5.
  • Названия тегов и свойств в правилах пишутся строчными буквами.
  • Начальный ноль для значений не сокращается (например, .5 вместо 0.5).
  • Во всех случаях в стилях используются двойные кавычки. В необязательных случаях кавычки не опускаются.
  • После двоеточия в правилах ставится один пробел (top: 10px;). А перед двоеточием пробел не нужен.
  • После запятых внутри значений rgb(), rgba(), hsl(), hsla() или rect() пробелы ставятся. Это повышает удобочитаемость.
  • До и после комбинатора между селекторами (например, p > a) ставится один пробел.
  • Каждое объявление в правиле пишется на новой строке.
  • Перед открывающейся фигурной скобкой ставится один пробел. После скобки запись идёт с новой строки:
    .selector {
      color: #f5f5f5;
    }
                
  • Закрывающая фигурная скобка пишется на новой строке и без отступа. Следующее после этого правило отделяется пустой строкой.
  • Единицы измерения не пишутся, там где в них нет необходимости. Например, border: 0.
  • Для проверки CSS-кода используйте конфигурацию для настройки валидатора stylelint.
  • Для автоматического применения этих правил используйте файл конфигурации csscomb.json для настройки CSSComb.
/* Хорошо */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0, 0, 0, 0.5);
  box-shadow: 0 1px 2px #cccccc, inset 0 1px 0 #ffffff;
}

/* Плохо */
.selector, .selector-secondary, .selector[type=text]{
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0,0,0,.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF}

Порядок свойств

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

  1. Позиционирование
  2. Блочная модель
  3. Типографика
  4. Оформление
  5. Анимация
  6. Разное

Позиционирование следует первым потому, что оно влияет на положение блоков в потоке документа. Блочная модель идёт следующей, так как она определяет размеры и расположение блоков.

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

Сгруппированные объявления в правиле отделяются друг от друга пустой строкой.

Порядок объявления подробных правил, таких как font-size, font-family, line-height, должен соответствовать порядку в сокращённой версии правила. В случае совместного использования подробных и сокращённых правил, первой должна идти сокращённая версия.

.declaration-order {
  /* Позиционирование */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Блочная модель */
  display: block;
  float: right;
  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;

  /* Типографика */
  font: normal 13px/1.5 "Arial", sans-serif;
  font-style: normal;
  font-size: 13px;
  line-height: 1.5;
  font-family: "Arial", sans-serif;
  text-align: center;
  color: #333333;

  /* Оформление */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;
  opacity: 1;

  /* Анимация */
  transition: color 1s;

  /* Разное */
  will-change: auto;
}

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

  • Имена классов пишутся строчными буквами, используется дефис (но не знаки нижнего подчёркивания или camelCase). Дефисы служат разделителями во взаимосвязанных классах (например, .button и .button-danger).
  • Имена классов должны быть такими, чтобы по ним можно было быстро понять какому элементу страницы задан класс: избегайте сокращений (единственное исключение — .btn для кнопок), но не делайте их слишком длинными (более трёх слов).
  • Для написания классов используются английские слова и термины. Транслитом названия классов и атрибутов не пишутся.
/* Хорошо */
.alert-danger { … }
.tweet .user-picture { … }
.button { … }
.layout-center { … }

/* Плохо */
.testElement { … }
.t { … }
.big_red_button { … }
.knopka { … }

Правило @import

Правило @import работает медленнее, чем тег <link>. В стилях @import не должен использоваться.

<!-- Хорошо: подключение тегом link -->
<link rel="stylesheet" href="module.css">

<!-- Плохо -->
<style>
  @import url("module.css");
</style>

Варианты шрифта

Альтернативные варианты шрифта и тип семейства указываются в конце перечисления font-family.

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

Порядок шрифтов следующий:

  1. нестандартный шрифт;
  2. веб-безопасный;
  3. тип шрифта.

Список веб-безопасных шрифтов можно посмотреть здесь — cssfontstack.com.

/* Хорошо: указан альтернативный веб-безопасный шрифт и его тип семейства */
body {
  font-family: "Helvetica", "Arial", sans-serif;
}

/* Кому-то нравится Arial, кому-то Tahoma */
body {
  font-family: "Helvetica", "Tahoma", sans-serif;
}

/* Плохо: указан только нестандартный шрифт */
body {
  font-family: "Helvetica";
}

/* Плохо: указан только нестандартный шрифт и тип семейства, альтернативный веб-безопасный шрифт отсутствует */
body {
  font-family: "Helvetica", sans-serif;
}

/* Плохо: Georgia — шрифт с засечками, а нестандартный шрифт — без засечек */
body {
  font-family: "Helvetica", "Georgia", sans-serif;
}