FRONTEND GUIDELINE

frontend__gudeline.txt

frontend (read: http://cssguidelin.es/)


    Общее

        — Ширина кода по возможности 80 символов, максимум — 120 символов

        — Отступ 4 пробела (не табуляция!)

        — Комментируйте где что используется, что переопределяется, от чего наследуется. 
        Лучше написать лишнего, чем забыть описать важное.





    HTML

        — Названия классов и оформление кода должны обеспечивать легкую поддержку кода в будущем 
        и безпроблемную передачу кода другому разработчику

        — Классы для стилей называть по БЭМ-методологии (см. раздел БЭМ)

        — Названия классов должны ясно выражать:
            — почему необходимо выделить именно эти элементы в DOM-дереве
            — для каких целей используются элементы с этим классом

        - Классы для CSS, организованные по БЭМ, начинать с «b-»
        
        — ОБЯЗАТЕЛЬНО Классы для JS начинать с «js-»

        — Один класс ДОЛЖЕН использоваться либо только для стилей, либо только для javascript
            <input type="submit" class="b-btn js-btn">

        — НЕЛЬЗЯ использовать id для стилей и js

        — CSS-стили привязывать только к классам (не использовать id)

        — JS-события привязывать только к классам (не использовать id)

        — Данные для JS хранить в атрибутах начинающихся с «data-»

        — НЕЛЬЗЯ ставить закрывающий слеш у одиночных атрибутов
            // Нет
            <br/>

            // Да
            <br>

        — Всегда ставить двойные кавычки у атрибутов
            <div class="b-box">

        — НЕ СЛЕДУЕТ встраивать CSS через атрибут style, если это все же происходит, то:
            — ОБЯЗАТЕЛЬНО после двоеточия пробел
            — ОБЯЗАТЕЛЬНО точка с запятой, даже у последнего
            — ОБЯЗАТЕЛЬНО после точки с запятой пробел, кроме последней
            — Внутри кавычек не должно быть отступов-пробелов от самих кавычек
            — ЖЕЛАТЕЛЬНО каждый стиль помещать на отдельную строчку c выравниванием, особенно если больше трех 
            Пример: <div style="border: 1px solid black; font-size: 16px;">
            Пример: <div style="border: 1px solid black; 
                                font-size: 16px;
                                height: 150px;
                                width: 400px;">

        — МОЖНО разделять блоки одним, двумя или пятью брейками. Больше никакими. Как минимум один брейк.

        — Якоря. Оформление заголовков с якорными ссылками
                <h3><a id="events" href="#events" name="events">Спонсирование мероприятий</a></h3>
            Ссылка на якорь должна быть относительной, т.е. начинаться с решетки.
            Якорь должен быть в нижнем регистре, пробелы заменяются дефисами, должен совпадать с контентом.
            Технически якоря могут быть русскоязычными, но их можно использовать только с аппрува менеджера.





    БЭМ (read: http://ru.bem.info/articles/bem-for-small-projects/) (watch: http://www.youtube.com/watch?v=RM55tkWfHDc)

        Для имен классов используем БЭМ-поход

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


        Правила именования пременных:
            имена блоков, элементов и модификаторов должны быть недлинными и семантически значимыми;
            используем только латинские буквы, дефис и цифры;
            не используем символ подчёркивания (_), он нам понадобится как специальный разделитель.

        ОБЯЗАТЕЛЬНО имя блока начинать с «b-»

        Элемент отделяется двумя прочерками (__)
        Модификатор отделяется двумя дефисами (--)

        Если модификатор — пара «ключ-значение», добавляем ещё одно подчёркивание для отделения значения модификатора:
            .b-heading--level_alpha

        Классы-модификаторы используются совместно с классом блока или элемента:
            <div class="b-heading b-heading--level_alpha">BEM</div>

        Общий паттерн именования:
            названи-блока__название-элемента--название-модификатора_значение-модификатора {}

        Аналогия из жизни:
        .человек {}
        .человек__голова {}
        .человек--высокий {}
        .человек__голова--лысая {}


        НЕЛЬЗЯ делать элементы элементов: НЕПРАВИЛЬНО .block__elem1__elem2 НЕПРАВИЛЬНО

        МОЖНО вкладывать один блок в другой, но вместо наследования (каскада) в стилях лучше использовать модификатор блока
            Пример: мы имеем два блока, один вложен в другой, допустим это меню и пункт меню, обычно делаем так:
                .menu {
                    ...
                } 
                
                .menu .link {
                    ...
                }
            Этот подход выше достаточно плох, поскольку слишком общий, слишком специфичный и сложно ищется. 
            БЭМ же, во избежание этих проблем, предлагает делать так:
                .b-top-menu {
                    ...
                }
                
                .b-top-menu__link {
                    ...
                }



    CSS

        - Использвать БЭМ (см. раздел БЭМ)

        — ОБЯЗАТЕЛЬНО использовать только классы. В CSS ЗАПРЕЩЕНО использоваться аттрибут id.

        — НЕЖЕЛАТЕЛЬНО использовать привязку классов к тэгам (e.g. ul.menu). Только классы.

        — МОЖНО использовать чистые тэги, для формирования базовых стилей (a, p, h1, h2, h3, h4 etc.)

        — НЕ СЛЕДУЕТ использовать наследование и вложенность элементов, кроме редких случаев. Старайтесь всегда использовать одиночные классы. В этом поможет БЭМ-поход (read: http://csswizardry.com/2012/05/keep-your-css-selectors-short/)
            ХОРОШО:
                .b-box {
                    display: block;
                    padding: 10px;
                }

                .b-box--large {
                    padding: 20px;
                }
            ПЛОХО:
                .box {
                    display: block;
                    padding: 10px;
                }

                .content .box {
                    padding: 20px;
                }

        — Очень аккуратно использовать !important, не использовать для хаков и быстрых фиксов
            Хороший пример использования
            .hidden{display: none !important;}
            Здесь мы гарантируем скрытость элемента с классом .hidden
            
        — НЕЛЬЗЯ использовать !important для решения проблем со специфичностью

        — Разделяйте стили на секции и файлы
            — МОЖНО разделять блоки одним, двумя или пятью брейками. Больше никакими. Как минимум один брейк.
            — Каждую секцию предваряйте заголовком, перед названием секции можно ставить «#», не забывайте отбивать заголовок секции дополнительным брейком перед первым селектором ниже
                /*------------------------------------*\
                    A SECTION
                \*------------------------------------*/

                .b-selector {}
                
            — Если в файле несколько секций, то каждую следующую секцию отбивать пятью брейками. После комментария о секции обязательно один брейк
                /*------------------------------------*\
                    A SECTION
                \*------------------------------------*/

                .b-selector {}





                /*------------------------------------*\
                    ANOTHER SECTION
                \*------------------------------------*/

                /**
                 * Comment
                 */

                .b-another-selector {}

        — Форматирование стилей:
                [селектор] {
                    [свойство]: [значение];
                    [<----декларация---->]
                }

                .b-foo, .b-foo--bar,
                .b-bazz {
                    display          : block;
                    background-color : green;
                    color            : red;
                }
            — Отступ 4 пробела (не табуляция, а пробелы!)
            — Родственные селекторы на одной линии
            — Открывающая скобка на той же строке, что и последний селектор
            — Пробел перед открывающей скобкой ({)
            — Закрывающая скобка на отдельной строке (})
            — Первая декларация на отдельной строке после открывающей скобки
            — Каждая декларация на отдельной строке
            — Пробел после двоеточия (:)
            — Точка с запятой (;) в конце каждой декларации, даже последней
            — У единичной декларации двоеточие вплотную к свойству, без пробела между ними
            ЛИБО - Выравнивание с толбик по двоеточию, тогда слева и справа от двоеточия минимум один пробел. 
                Делается автоматически по CMD+SHIFT+ENTER в PhpStorm 
                Выбрать в PhpStorm опцию Editor > Code Style > CSS Algine values: On colon


        — Какие бывают ошибки в форматировании стилей:
            — НЕПРАВИЛЬНО табы вместо пробелов
            — НЕПРАВИЛЬНО никак не связанные логические селекторы на одной линии
            — НЕПРАВИЛЬНО открывающая скобка ({) на отдельной линии
            — НЕПРАВИЛЬНО закрывающая скобка (}) не на отдельной линии
            — НЕПРАВИЛЬНО пропущена последняя точка с запятой (;)
            — НЕПРАВИЛЬНО нет пробела после двоеточия (:)

        — МОЖНО стили с одной декларацией писать на одной линии
            .b-icon {
                display          : inline-block;
                width            : 16px;
                height           : 16px;
                background-image : url(/img/sprite.svg);
            }

            .b-icon--home     { background-position:   0     0  ; }
            .b-icon--person   { background-position: -16px   0  ; }
            .b-icon--files    { background-position:   0   -16px; }
            .b-icon--settings { background-position: -16px -16px; }

        — Делать отступ у вложенных БЭМ-стилей
            .b-foo {}

                .b-foo__bar {}

        — Брейки между стилями
            — 1 брейк между близкими по смыслу стилями
            — 2 брейка между слабо связанными стилями
            — 5 брейков между секциями
            — НЕПРАВИЛЬНО вообще не ставить брейк
            
            Пример правильных брейков:
            
                /*------------------------------------*\
                    #FOO
                \*------------------------------------*/

                .foo {}

                    .foo__bar {}


                    .foo--baz {}





                /*------------------------------------*\
                    #BAR
                \*------------------------------------*/

                .bar {}

                    .bar__baz {}

                    .bar__foo {}


        — ОБЯЗАТЕЛЬНО Использовать «0» вместо «0px»
            margin: 0;

        — Использовать компактную запись отступов
            margin  : 20px 0 10px 0;
            margin  : 0 auto;
            padding : 20px 0 10px 0;

        — При использовании экспериментальных свойств свойство без перфикса помещать последним. МОЖНО объединить их в одну строку
            -webkit-transition : all 100ms;
            transition         : all 100ms;





    jQuery (read: http://programer.tips/2014/09/best-jquery-practices.html)

        — НЕЛЬЗЯ подключать jQuery, другие библиотеки и шрифты через CDN

        — В продакшне использовать только сжатые (.min) версии библиотек

        — Помещать скрипты не в <head> а перед закрывающим </body>, где это возможно. Это ускорит загрузку страницы

        — Использовать полную запись для ready, можно вбить ее в Live Templates в PhpStorm
            // Обычно пишем так
            $(document).ready(function() {
                ...
            });

            // Сокращенная версия, лучше не использовать, т.к. такая конструкция менее понятна
            $(function() {

            });

        — Переменные с jQuery-объектами именовать начиная с «j». Тогда по коду будет ясно, где обычная переменная, а где jQuery-объект. Доллар плох, так как распознается мозгом как php-переменная, поэтому префикс «j»
            // Нет
            var form = $('#contactForm');
            var contact_form = $('#contactForm');

            // Да
            var jForm = $('js-contact-form');
            var jContactForm = $('js-contact-form');


        — Использование jThat для передачи jQuery-контекста

            $('.js-menu__li').each(function() {
                var jThat = $(this);
                jThat.on('click', function() {
                    jThat.addClass('active');
                });
            });

        — Повторные выборки кешируем в переменные

            // Нет
            $('.js-menu__li').each(function() { ... });
            $('.js-menu__li').each(function() { ... });

            // Да
            var jItems = $('.js-menu__li');
            jItems.each(function() { ... });
            jItems.each(function() { ... });

        — Используем цепочки.

            // Нет, но бывают исключения, когда так лучше
            var jAbout = $('.js-about');
            jAbout.hide();
            jAbout.addClass();
            jAbout.fadeIn();
            jAbout.hide();
            
            // Да
            $('.js-about').hide().addClass().fadeIn().hide();

            // С брейками посимпатичнее
            $('js-about')
                .hide()
                .addClass()
                .fadeIn()
                .hide();

        — Создаем элементы с помощью методов jQuery

            // Нет, но бывают исключения, когда так лучше
            var jHidden = $('<input class="b-form-control" type="hidden" name="foo" value="bar">').appendTo('js-form');

            // Да
            var jHidden = $('<input>')
                            .addClass('b-form-control')
                            .attr('type', 'hidden')
                            .attr('name', 'foo')
                            .val('bar')
                            .appendTo('js-form');

            // Да
            var jHidden = $('<input>', {
                                class: 'b-form-control',
                                type: 'hidden',
                                name: 'foo',
                                value: 'bar'
                            }).appendTo('js-form');

        — Лучше использовать методы, чем селекторы, потому что быстрее

            // Нет
            $('.b-item:first')

            // Да
            $('.b-item').first()
            
        — Не используем короткую запись для добавления событий, а используем делегирование
            
            // Нет
            $(...).click(...)
            
            // Да
            $(...).on('click', ...)

        — Для запуска событий ОБЯЗАТЕЛЬНО используем trigger
        
            // Нет
            $(...).click()
            
            // Да
            $(...).trigger('click')




    Источники

        — http://blog.trello.com/refining-the-way-we-structure-our-css-at-trello/

        — http://cssguidelin.es/

        — http://www.youtube.com/watch?v=RM55tkWfHDc

        — http://csswizardry.com/2012/05/keep-your-css-selectors-short/

        — http://www.impressivewebs.com/modular-css-media-queries-sass/

        — http://programer.tips/2014/09/best-jquery-practices.html