CSS GuideLines, часть 2. Комментирование кода
В каждом проекте есть определенные нюансы и тонкости, которые помнят далеко не все, и худшее, что может случиться с разработчиком — это работа с кодом, который писал не он. Даже запоминание тонкостей своего собственного кода является возможным только до определенной степени, не говоря уже о чужом коде. Именно поэтому CSS надо комментировать.
- Что какой-то кусок кода зависит от другого куска;
- Какой эффект повлечет за собой изменение определенной части кода;
- Где еще можно использовать кусок кода без появления новых проблем;
- Какие стили наследует определенный элемент;
- Какие стили могут быть проигнорированы;
- Где разработчик намеревался использовать код.
Так как CSS сам по себе не может быть достаточно понятным, то разработчики действительно получают выгоду от комментирования кода.
Как правило, следует комментировать те места кода, которые будут непонятны разработчику, если вырвать их из контекста. Нет необходимости делать пометку о том, что color: red; сделает текст красным. Но, например, если вы используете свойство overflow: hidden; для очистки float’ов, а не для скрытия контента за пределами блока, то вам следовало бы добавить пояснительный комментарий.
Высокоуровневые комментарии
Для больших комментариев, описывающих целую секцию или компонент, мы используем DocBlock-подобные мультистрочные комментарии, соответствующие нашему правилу о 80 символах в строке.
Ниже можно увидеть реальный пример комментирования кода шапки сайта CSSWizardy.
Этот уровень комментирования должен использоваться для описания элемента в общем: его состояния, от чего это состояние зависит и тому подобное.
Указание на наследование стилей
Когда вы работаете с большим количеством файлов, то не всегда наборы правил, относящиеся друг к другу, будут находиться в одном и том же файле. Например, у вас может быть главный класс .btn , содержащий в себе только основные стили кнопки (размеры и отступы, например). Этот класс расширяется в файле компонентов, там в него добавляются стили для придания нужного внешнего вида. Эти связи между объектами мы должны обозначить с помощью указания на наследование стилей.
Например, в файле с главным классами (объектами):
В файле с дочерними классами:
Такое комментирование кода не потребует от разработчика больших усилий, и благодаря этим комментариям те, кому придется работать с вашим кодом, легко смогут разобраться в связях между классами.
Низкоуровневые комментарии
Часто нам требуется прокомментировать определенную строку кода с объявлением какого-либо свойства. Для этого мы используем сноски. По ссылке можно увидеть пример более сложного комментирования кода шапки сайта, о которой говорилось выше. Такой способ комментирования позволяет нам держать всю документацию в одном месте, и затем всего лишь ссылаться на нужное место в документации, вместо того, чтобы писать длинный комментарий прямо в коде.
Препроцессоры и комментирование
Во многих, если не во всех препроцессорах есть возможность добавлять комментарии, которые при компиляции не будут выводиться в итоговый файл стилей. Примите за правило использовать такие комментарии для кода, который также не будет скомпилирован. Для кода, который будет выведен в итоговый файл, используйте обычные комментарии.
В этом примере мы задокументировали переменные (которые не будут скомпилированы) с помощью комментариев препроцессора, а для обычного кода мы применили стандартный способ комментирования. Такой способ гарантирует нам то, что в скомпилированных CSS-файлах будет только релевантная и нужная для нас информация.
Удаление комментариев
Следует сказать о том, что при использовании кода в продакшене все комментарии должны быть удалены, а сам CSS должен быть минифицирован перед деплоем.
Комментарии в CSS
Комментарии в CSS нужны, чтобы комментировать отдельные куски кода или быстро временно отключать свойства без удаления их из кода.
Комментарии не влияют на работу остального кода, а значит невозможно увидеть их, не заглядывая в файл со стилями.
Часто комментарии используются для визуального отделения блоков стилей друг от друга. Например, чтобы отделить стили для шапки сайта от стилей для остальной страницы.
Пример
В CSS существует только один вид комментариев, но их можно записывать по-разному.
Обратите внимание, что комментарий вида / / в начале строки в CSS не поддерживается, он работает только в препроцессорах, вроде Sass или Less.
Как пишется
Комментарий оформляется при помощи двух пар символов, / * и * / :
По желанию или в соответствии с принятым в вашей команде стилем кода после открывающих символов можно перенести текст на новую строку, и закрывающую пару тоже поставить на следующей новой строке. Как-то так:
Как это понять
У комментария обязательно должны быть начало и конец. Открывать комментарий нужно при помощи / * , а закрывать — при помощи зеркальной конструкции * / .
Ещё пример
Как выглядит закомментированное свойство:
А вот так можно закомментировать целый блок:
Иногда комментариями обозначают начало и конец смысловых блоков стилей:
В таком коротком куске кода комментарии избыточны и смотрятся грязно. Но когда файл со стилями состоит из тысяч строк (такого, конечно, стоит избегать), то такая навигация удобна.
Подсказки
�� Не злоупотребляйте комментариями. Не стоит пояснять всё подряд. Пишите комментарии только там, где без подсказки никак не понять, что происходит.
�� Но и не игнорируйте комментарии. Не молчите там, где есть что сказать. Например, вы использовали !important в коде (напомним, что это крайне нежелательная практика), но в данном случае он необходим. Поясните своё решение, чтобы следующий разработчик всё не сломал, удалив нежелательный элемент.
�� Чтобы быстро закомментировать или раскомментировать текущую строку или выделенный блок кода, в большинстве редакторов кода можно нажать Ctrl / или Cmd / .
На практике
Егор Левченко
�� Иногда в процессе разработки нужно быстро проверять какую-то гипотезу. Не хочется сгоряча удалять блок кода, вымученного кровью и потом. Просто закомментируй подозрительные строки. Если причина не в них, то раскомментируешь. Удалить всегда успеешь.
�� Удаляй все закомментированные свойства перед деплоем — публикацией проекта. Комментарии — утилитарная штука. Они полезны, но сильно загружают код и затрудняют его чтение. Если это не информационные комментарии, а следы экспериментов — удаляй их.
�� Иногда можно встретить в начале файла своеобразное оглавление, поясняющее в какой части файла искать стили для того или другого блока. Если у вас очень большой файл, то стоит попробовать такой подход. Он может оказаться удобным.
Алёна Батицкая
�� Как всегда, стоит удалить все те комментарии, которые не должен видеть заказчик или пользователь конечного продукта, перед деплоем. Все, что неактуально, решено, касается внутренних процессов в вашей компании и не будет использоваться в дальнейшем — смело под нож!
Что нужно знать о комментариях в CSS
В CSS вы можете добавлять комментарии, чтобы объяснить или организовать различные разделы таблицы стилей. Это может показаться лишним шагом в процессе кодирования, но комментарии могут быть чрезвычайно полезны при отладке или редизайне вашего сайта.
Почему? Потому что они рассказывают читателю, какова цель конкретных строк CSS. Эти идеи особенно полезны, если над веб-сайтом работают несколько разработчиков или если вы унаследовали сайт от другого владельца.
Если вы раньше просматривали таблицу стилей или читали достаточно сообщений в блоге с фрагментами кода, возможно, вы уже видели комментарии. Их можно узнать по знакам / /, которые их окружают.
В этом посте мы рассмотрим, как создавать собственные комментарии. Затем мы рассмотрим, что значит «закомментировать» в CSS и как это сделать. Давайте начнем.
Как комментировать в CSS
Чтобы оставить комментарий в CSS, просто поместите свой простой текст внутри / / знаков. Это сообщает браузеру, что это заметки и не должны отображаться в интерфейсе пользователя.
Вы можете добавлять комментарии в таблицу стилей двумя способами. Наиболее распространенный формат – однострочный комментарий, как показано в приведенном ниже коде.
Вы также можете отформатировать их как многострочные комментарии, как показано в приведенном ниже коде.
Вы можете поместить любой из этих фрагментов кода в раздел своей веб-страницы или во внешнюю таблицу стилей CSS для стилизации следующего HTML.
Если вы используете CSS-фреймворк Bootstrap вместо создания веб-сайта с нуля, комментирование по-прежнему работает точно так же.
Вот CSS, который остался прежним:
HTML будет немного другим, просто потому, что я хочу поместить элемент заголовка и абзаца в контейнер полной ширины, чтобы по краям было немного отступов.
Вот результат. Примечание. Единственная разница во внешнем интерфейсе – это семейство шрифтов, которое задается глобально в Bootstrap.
Как "закомментировать" в CSS
Помимо объяснения разделов кода, комментарии также могут использоваться для признания недействительным набора правил CSS или отдельных объявлений. Поместив знаки / / вокруг набора правил или объявления, вы можете «закомментировать» этот CSS, чтобы браузер знал, что этот стиль не следует применять.
Прежде чем продолжить, давайте выясним, что такое набор правил. Набор правил – это селектор CSS и все объявления внутри скобок. Ниже приведен набор правил для всех элементов абзаца на веб-странице (который мы использовали в примерах выше).
Теперь давайте рассмотрим пример закомментированного отдельного объявления в этом наборе правил.
Теперь мы рассмотрим пример, когда весь набор правил закомментирован.
Создание комментариев в вашем CSS
Если вы хотите добавить пояснительные примечания или запретить браузеру отображать определенные части вашей таблицы стилей, вы можете использовать комментарии. Комментарии не повлияют на интерпретацию других частей вашей таблицы стилей или макет вашего веб-сайта в интерфейсе пользователя. Их также легко создавать, даже если вы только начинаете изучать HTML и CSS.