Руководство по написанию кода

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

Оглавление

HTML

CSS

Золотое правило

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

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

HTML

Синтаксис

      <nav class="main-nav">
        <ul>
          <li><a href="/index.html">Главная</a></li>
          <li><a href="/contacts.html">Контакты</a></li>
        </ul>
      </nav>
      <br>
      <img src="logo.svg" width="50" height="50" alt="Company">
    

Обязательные компоненты разметки

      <!DOCTYPE html>
      <html lang="ru">
        <head>
          <meta charset="UTF-8">
          <title>Заголовок страницы</title>
        </head>
        <body>
          <img src="logo.svg" width="50" height="50" alt="Company">
          <h1>Привет, мир!</h1>
        </body>
      </html>
    

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

При подключении CSS и JavaScript файлов не указывайте атрибут type (text/css для стилей и text/javascript для скриптов являются значениями по умолчанию).

CSS-файлы подключайте в <head>, JavaScript-файлы — перед </body>

      <!-- Внешний CSS -->
      <link rel="stylesheet" href="style.css">
       
      <!-- Внешний JavaScript -->
      <script src="script.js"></script>
    

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

Очередность атрибутов должна быть единообразной.

Указывайте атрибуты data-*, aria-*, role и логические атрибуты последними.

      <a class="btn" href="#modal-call-me" data-modal="toggle">Перезвоните</a>
       
      <input type="text" class="field-text" disabled>
       
      <img src="logo.svg" width="50" height="50" alt="Company">
    

Разное

      <header class="page-header">
        <a href="/" class="logo">
          <img src="logo.svg" width="50" height="50" alt="Company">
        </a>
        ...
        <a href="/login" class="login">Войти</a>
        <!-- <a href="/logout" class="login">Выйти</a> -->
      </header>
       
      <section class="catalog">
        ...
      </section>
    

CSS

Синтаксис

      /* Хороший CSS */
      .selector > .some,
      .selector-secondary {
        padding: 15px;
        margin: 0 0 15px;
        line-height: 1;
        background-color: rgba(0,0,0,0.5);
        box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
      }
       
      /* Плохой CSS */
      .selector>.some ,.selector-secondary{
        padding:15px;
          margin:0 0px 15px;
         line-height :1em;
        background-color: rgba(0, 0, 0, .5);
        box-shadow:0 1px 2px #ccc,inset 0 1px 0 #FFF;}
    

Селекторы

Используйте БЭМ-именование, если знакомы с этой методологией.

      /* Хорошие селекторы */
      .pahe-header { ... }
      .comment { ... }
      .sidebar { ... }
      .gallery { ... }
      .gallery__item { ... }
       
      /* Плохие селекторы */
      .t { ... }
      .root span a { ... }
      .red { ... }
      .my_block { ... }
      .HeaderOfMyBlock { ... }
      .eto-moy-perviy-klass { ... }
    

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

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

  1. Позиционирование
  2. Блочная модель и размеры
  3. Текстовые свойства
  4. Отображение
  5. Остальное
  6. Плавные переходы, анимация

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

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

      .selector {
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
        z-index: 100;
         
        display: block;
        float: right;
        width: 100px;
        height: 100px;
         
        font: 13px/1.5 "Helvetica Neue", sans-serif;
        color: #333;
        text-align: center;
         
        background-color: #f5f5f5;
        border: 1px solid #e5e5e5;
        border-radius: 3px;
        opacity: 1;
         
        transition: all 0.3s;
      }
    

Быстрое чтение

Оставляте пустую строку перед селектором или группой селекторов.

Работая с CSS-препроцессорами, оставляйте пустую строку перед любым вложенным селектором и @media.

      /* В CSS-файле: */
      .promo {...}
       
      .gallery {...}
       
      /* В препроцессорном файле: */
      .promo {
        display: block;
       
        &__container {...}
       
        &__item {...}
      }
    

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

Избегайте сокращенных объявлений. К примеру, если нужно задать только нижний внешний отступ, пишите margin-bottom: 10px; вместо margin: 0 0 10px;

      /* Хорошо */
      .element {
        margin-bottom: 10px;
        background-color: red;
        background-image: url("image.jpg");
        border-top-left-radius: 3px;
        border-top-right-radius: 3px;
      }
       
      /* Плохо */
      .element {
        margin: 0 0 10px;
        background: red;
        background: url("image.jpg");
        border-radius: 3px 3px 0 0;
      }
    

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

По сравнению с тегом <link> правило @import работает медленнее и может вызвать иные непредвиденные проблемы. Не используйте @import, используйте альтернативные подходы:

      <!-- Используйте тег link -->
      <link rel="stylesheet" href="style.css">
       
      <!-- Не используйте @imports -->
      <style>
        @import url("more-styles.css"); /* Плохо! Не надо так! */
      </style>
    

@media

Помещайте media queries настолько близко к соответствующим наборам правил, насколько это возможно. Не объединяйте их в отдельную таблицу стилей, не помещайте их в конце файла.

Ставьте пробелы вокруг полукруглых скобок.

Ставьте пробел перед указанием значения в условии.

      /* В CSS-файле (без препроцессоров): */
      .element {
        display: block;
      }
       
      @media (min-width: 480px) {
        .element {
          display: none;
        }
      }
       
      /* В препроцессорном файле: */
      .element {
        display: block;
       
        @media (min-width: $screen-sm) {
          display: none;
        }
      }
    

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

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

Не пишите свойства с вендорными префиксами вручную. Используете Autoprefixer в рамках автоматизации или его он-лайн сервис.

      .selector {
        -webkit-box-shadow: 0 1px 2px rgba(0,0,0,0.15);
                box-shadow: 0 1px 2px rgba(0,0,0,0.15);
      }