CSS GuideLines, часть 2. Комментирование кода

Original author: Harry Roberts
  • Translation
  • Tutorial


В каждом проекте есть определенные нюансы и тонкости, которые помнят далеко не все, и худшее, что может случиться с разработчиком — это работа с кодом, который писал не он. Даже запоминание тонкостей своего собственного кода является возможным только до определенной степени, не говоря уже о чужом коде. Именно поэтому CSS надо комментировать.

CSS это декларативный язык, и часто бывает трудно понять:
  • Что какой-то кусок кода зависит от другого куска;
  • Какой эффект повлечет за собой изменение определенной части кода;
  • Где еще можно использовать кусок кода без появления новых проблем;
  • Какие стили наследует определенный элемент;
  • Какие стили могут быть проигнорированы;
  • Где разработчик намеревался использовать код.

Этот список даже не затрагивает многих причуд CSS, таких как включение аппаратного ускорения с помощью свойтсва transform, а ведь такие вещи тоже усложняют понимание того, что делает код.

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

Как правило, следует комментировать те места кода, которые будут непонятны разработчику, если вырвать их из контекста. Нет необходимости делать пометку о том, что color: red; сделает текст красным. Но, например, если вы используете свойство overflow: hidden; для очистки float'ов, а не для скрытия контента за пределами блока, то вам следовало бы добавить пояснительный комментарий.

Высокоуровневые комментарии


Для больших комментариев, описывающих целую секцию или компонент, мы используем DocBlock-подобные мультистрочные комментарии, соответствующие нашему правилу о 80 символах в строке.

Ниже можно увидеть реальный пример комментирования кода шапки сайта CSSWizardy.

/**
 * The site’s main page-head can have two different states:
 *
 * 1) Regular page-head with no backgrounds or extra treatments; it just
 *    contains the logo and nav.
 * 2) A masthead that has a fluid-height (becoming fixed after a certain point)
 *    which has a large background image, and some supporting text.
 *
 * The regular page-head is incredibly simple, but the masthead version has some
 * slightly intermingled dependency with the wrapper that lives inside it.
 */

Этот уровень комментирования должен использоваться для описания элемента в общем: его состояния, от чего это состояние зависит и тому подобное.

Указание на наследование стилей

Когда вы работаете с большим количеством файлов, то не всегда наборы правил, относящиеся друг к другу, будут находиться в одном и том же файле. Например, у вас может быть главный класс .btn, содержащий в себе только основные стили кнопки (размеры и отступы, например). Этот класс расширяется в файле компонентов, там в него добавляются стили для придания нужного внешнего вида. Эти связи между объектами мы должны обозначить с помощью указания на наследование стилей.

Например, в файле с главным классами (объектами):

/**
 * Extend `.btn {}` in _components.buttons.scss.
 */

.btn {}

В файле с дочерними классами:

/**
 * These rules extend `.btn {}` in _objects.buttons.scss.
 */

.btn--positive {}

.btn--negative {}

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

Низкоуровневые комментарии


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

Препроцессоры и комментирование


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

Так правильно:

// Dimensions of the @2x image sprite:
$sprite-width:  920px;
$sprite-height: 212px;

/**
 * 1. Default icon size is 16px.
 * 2. Squash down the retina sprite to display at the correct size.
 */
.sprite {
    width:  16px; /* [1] */
    height: 16px; /* [1] */
    background-image: url(/img/sprites/main.png);
    background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */
}

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

Удаление комментариев


Следует сказать о том, что при использовании кода в продакшене все комментарии должны быть удалены, а сам CSS должен быть минифицирован перед деплоем.

Предыдущая часть: CSS GuideLines, часть 1. Синтаксис и форматирование
Следующая часть: CSS GuideLines, часть 3. Именование классов
Share post

Similar posts

Comments 24

    –8
    CSS это декларативный язык, и часто бывает трудно понять — никогда не возникало трудности в понимании чьего либо css
    Что какой-то кусок кода зависит от другого куска — это покажет devtools и любая нормальная IDE
    Какой эффект повлечет за собой изменение определенной части кода — изменение оформления страницы
    Где еще можно использовать кусок кода без появления новых проблем — в селекторе, для которого стили и были описаны
    Какие стили наследует определенный элемент — те, что прописаны для его селектора. Firebug/DevTools в помощь
    Какие стили могут быть проигнорированы; — Firebug/DevTools в помощь
    Где разработчик намеревался использовать код. — это даже не смешно.
      0
      Зачем каждый раз лезть в Firebug / Devtools и смотреть стили для каждого селектора, если можно один раз закомментировать CSS и не открывать лишних окон?
        –7
        Я никогда туда не полезу. Ибо знаю свой код как пять рублей. Все просто и понятно. Все эти пляски с комментариями нужны будут лишь при передаче проекта другому человеку, который не сможет тебя спросить: чувак — что это за хрень? Чтобы разобраться в любом новом для тебя css коде проекта — понадобится несколько часов от силы. И то — если проект не маленький. Так лучше пускай новый человек потратит эти несколько часов один раз, чем я на протяжении всей свой работы буду судорожно комментировать весь свой код.
          –1
          Вот именно, что это надо при передаче проекта другому человеку. Как бы в первой части сказано, что эти рекомендации больше подходят для больших команд разработчиков, а не для тех, кто сам весь проект работает со своим кодом, так что ваша критика несколько неуместна.
            –3
            В первом же абзаце текста ставятся под сомнение сообразительные качества единственного разработчика со своим же кодом.
            В любой нормальной команде для решения подобных задач давно есть решения. БЭМ, Source, бутстрап(прости, господи). Даже богомерзкий бутстрап будет лучшим решением, чем то, что описано с топике.
              0
              А при чем тут бутстрап? Топик вроде как не о CSS-фреймворках.
                –3
                Хотя бы при том, что избавляет от насущной проблемы.
                  0
                  От какой-такой проблемы он избавляет? В CSS GudeLines говорится о рекомендациях по оформлению кода, а не о том, что надо использовать какие-то монструозные фреймворки, в которых черт ногу сломит и которые вообще как-то не в тему.
                    0
                    Т.е. БЭМ не монструозная методика? :D
                      0
                      А зачем переводить стрелки на БЭМ? Да, монструозная, но есть и его модификации более легкие. Наверное некорректно сравнивать бутстрап с БЭМ'ом. Так от какой-такой проблемы избавляет бутстрап?
                        0
                        От бессмысленного комментирования верстки.

                        Вы мигом соглашаетесь с Norlin насчет БЭМ'а, но не выдерживаете малейшей критики того, о чем пишете. Вместо аргументов за использование советов британского чувака без работы пытаетесь найти слабые стороны моих аргументов.
                          0
                          Комментирования CSS, а не верстки. В первой части были описаны преимущества единого стиля по оформлению кода при работе в команде. Также там было сказано, что эти рекомендации ни на что не претендуют и автор лично их использовал не на одном проекте.

                          Да, я соглашаюсь насчет БЭМ'а, но он подходит не всем. Возможно в каком-то проекте и будет лишним делать комментарии, но мое личное мнение таково, что если придется делать комментарии, то в этой статье описаны весьма дельные советы по их оформлению. Вы можете быть несогласны, это дело ваше. Каждый использует то, что хочет, и эти советы не исключение. Хотите — используйте, хотите — нет.
                            0
                            Последнее предложение, конечно, ставит точку в нашем мини-споре, но это немного странная позиция. Я, например, за каждый свой топик готов бить пяткой в грудь, что этот подход очешунен и у него, в принципе нет достойных аналогов.
        +1
        Думаю, не следует бросаться в крайности. Для верстки писем и маленьких проектов, конечно, непонятно что комментировать, но в случае большого проекта, комментирование — это спасение. Мне нравятся вот это выступление: tohtml.it/post/72875975026. Опять же почти все системы документирования верстки типа KSS, StyleDocco завязаны на комментарии в css, которые они парсят.

        Так что комментарии для активно растущего проекта — это благо.
          0
          Я посмотрю выступление позже, так что пока на его счет ничего не скажу.

          И да, к письмам это не относится. Я не один год работал как над крупными, так и мелкими проектами в роли фронтендера в разных командах. Я к чему так рогом-то уперся: никто не любит комментировать свой код. А вот использовать относительно общепринятые методики согласны многие. Поэтому такой вариант более адекватен.
        +4
        Если использовать подход, аналогичный БЭМ (независимые блоки, стили разделены на много маленьких файлов) и адекватное именование классов (а не просто .btn1, .btn2 и т.д.) – то очень редко в стилях возникакет потребность в комментариях.
          0
          Согласен. Сам использую такой подход. Только не все любят БЭМ и подобные методологии, к сожалению.
            –5
            И вместо пропаганды БЭМ'а мы несем в массы топик, который несет в себе одну мысль. Комментируйте свой код для инвалидов, которые смогут его прочесть.
              0
              Опять же повторюсь, эти рекомендации не для разработчиков-одиночек, а для тех, кто работает в команде и часто передает свой код другим разработчикам.
                0
                В команде ещё более важно писать понятный код. Конечно, если есть строгий стайлгайд, который никто никак не хочет менять – тогда да, всё плохо. Но обычно есть возможность воздействовать на тимлида\руководителя, привести аргументы и т.д. Особенно, учитывая, что это принесёт больше пользы, чем простые комментарии (которые ещё тоже надо «пробить» для обязательного использования, и которые требуют дополнительных временных затрат от разработчиков)
          –1
          Товарищи, сливающие карму, потрудитесь объяснить причину, пожалуйста.
            0
            Видимо, статья не нравится
              0
              По-моему очевидно. Уже сколько на хабре было статей про комментарии в коде.
              Код должен быть таким, чтобы комментирование было не нужным. Это и про название переменных в javascript, и про логичные классы и селекторы в css (раз уж тема веба затронута).
              Нужно не комментарии писать к css (ну куда уж проще язык?), а качественно его писать.
              Комментирование можно допускать только в очень небольших объемах, особенно в препроцессорах (LESS, SASS), когда не всегда миксины или сложные конструкции с условиями и циклами легко понять сразу другому человеку. Опять же — если работа идет в команде — для комментирования есть система контроля версий.
              –1
              Вот читаю комменты тут и пробую переложить ситуацию с CSS на программный код. И вот, что получается:

              1) А зачам вообще комментировать? Код должен быть самодокументируемый!
              2) Стайлгайд это зло, потому что вместо того, чтоб изучать фреймворки и технологии, вы призываете программеров комментарии писать
              3) Вот если все программеры перейдут на такую-то методику и/или будут юзать вот такие инструменты, то вообще ничо комментировать не надо будет

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

              Only users with full accounts can post comments. Log in, please.