Мы принимаем к оплате:

«Подарочный сертификат» от нашего Учебного Центра – это лучший подарок для тех, кто Вам дорог! Оплате обучение и подарите Вашим родным и близким обучение по любому из курсов!!!

«Сертификат на повторное обучение» дает возможность повторно пройти обучение в нашем Учебном Центре со скидкой 1000 рублей!

А также:


Комментирование в css


CSSDoc — формат комментариев для CSS

Уже неоднократно видел утверждение, что CSS необходимо комментировать, чтобы потом было проще сориентироваться себе или тому, кто также поддерживает или будет в дальнейшем поддерживать ваш код. Но почему-то никто не предлагает использовать какой-то универсальный формат комментариев, который был бы понятен всем, хотя в программировании такое используется повсеместно: JavaDoc, JSDoc, PHPDoc и т.п.

Несложно догадаться, что рано или поздно кто-нибудь бы захотел использовать подобный формат комментариев в CSS и такой формат появился: CSSDoc. Спецификация пока что имеет статус черновика, но ничто не мешает начать пользоваться основными правилами уже сейчас.

Полную спецификацию я приводить не буду, а приведу лишь часто используемые теги, причём акцент будет сделан не на автодокументировании, а на использовании CSSDoc для людей, так что некоторых вещей вы всё-таки из этого поста не узнаете, печально.
Формат комментариев
Формат комментариев полностью соответствует формату в JavaDoc и ему подобных:/** * Я — оригинальный комментарий! * * У меня даже есть немного текста, который точно так же * оригинален и возможно даже несколько забавен * * @tag Значение тега * @one-more-tag true */ * This source code was highlighted with Source Code Highlighter.
Теги
tag и @one-more-tag являются тегами. Они в совокупности с их значениями и являются самым главным оружием в документировании CSS. Теги описываются в документации и служат для определения каких-либо свойств присущих файлу/секции/правилу (подробнее об этом ниже). Забавный фактик: по спецификации значением тега не может быть unicode-строка, на что мы дружно забьём, ибо спецификация ещё черновая, да и ограничение это в наш век является, мягко говоря, бредовым. Основные теги, которые вам наверняка захочется использовать:
  • @package — указывается в начале файла и указывает в какую библиотеку (проект и т.п.) он входит, т.е. служит для группировки файлов;
  • @subpackage — то же, что и @package, только означает вложенную в @package группу, например: какая-то часть проекта или библиотеки;
  • @section — для разделения файла на секции. В спецификации указано, что основным назначением является разбиение на секции по смыслу (reset, typography, layout), хотя ничто не мешает использовать как разделение соответственно структуре документа (header, footer);
  • @subsection — для разделения файла на подсекции;
  • bugfix — описание багфикса, здесь стоит описать кратко суть бага;
  • @workaround — не путать с bugfix. Стоит указывать когда вы используете какой-либо нетривиальный CSS для довольно простых вещей, не связанных с багами браузеров;
  • affected — список браузеров, на которые распространяется влияние бага, описанного в bugfix или @workaround. Если это задевает все браузеры, то можно не писать;
  • @css-for — список браузеров, для которых написано правило. Бывает, что какой-либо bugfix affected IE6, IE7, а правила мы с помощью т.н. «хаков» пишем отдельно для IE6 и отдельно для IE7;
  • @see — когда нужно указать ссылку на CSS файлы, в которых встречается что-то связанное с данным конкретным случаем;
  • @link — просто ссылка;
  • @valid — соответствует ли правило стандартам;
Следующие в комментариях не нуждаются, но если кому-то будет непонятно, то можно посмотреть русскоязычную документацию к JavaDoc или PHPDoc (надеюсь они существуют):
  • @todo Почистить зубы!
  • @author
  • @copyright Copyright 0-2010 by Evil Empire
  • @license
  • @date
  • @lastmodified
  • @version
  • @since
  • @revision
  • @since-revision
Пример
А теперь, чтобы всё прояснилось напишем пример:/** * @package portal * @version 0.1 * @author Joe Shmoe */

/**

* Это самый простой пример, поэтому используем самый * простой reset * * @section reset * @link www.google.com/search?q=reset+css */ * {   margin: 0;   padding: 0; }

/**

* Общие правила * * @section common */

/**

* @subsection inline-blocks */ .inline-block {   display: inline-block; }

/**

* Т.к. это всего-лишь пример я не стал выносить в отдельный файл * это и следующее правила * * @bugfix IE inline-blocks support * @link www.google.com/search?q=ie+inline-block * @affected IE6, IE7 * @css-for IE6 * @valid no */ * html .inline-block {   display: inline;   zoom: 1; }

/**

* @bugfix IE inline-blocks support * @link www.google.com/search?q=ie+inline-block * @affected IE6, IE7 * @css-for IE7 * @valid no */ *+html .inline-block {   display: inline;   zoom: 1; } * This source code was highlighted with Source Code Highlighter. Как пользоваться остальными тегами, думаю, понятно. Пользуйтесь этим и тогда настанет мир во всём мире всем будет намного удобнее.

Кому интересно автодокументирование, то вот что получается в итоге.

Теги:
  • css
  • cssdoc
  • phpdoc
  • javadoc
  • jsdoc

Комментарии в CSS

CSS комментарии

Комментарий в CSS начинается с символов /* и заканчивается символами */ и может занимать несколько строк, его содержимое никак не отражается на разметку и игнорируется браузерами.

/*Комментарий 1*/ /* Многострочный Комментарий !!! */

Комментарии в CSS, могут применяться в разных случаях, напрмер:

  • Комментарии нужны, чтобы делать пояснения по поводу применения CSS свойств (Помогает разобраться в большом объеме кода) nav p{ padding-left:20px;/*Отступ слева для параграфов в навигации*/ }
  • Для разделения структурных блоков (если вы пишите весь css в одном файле, удобно размечать начало каждого следующего блока с помощью комментариев например:  /*Шапка*/ ... /*Навигация*/ ... /*Тело*/ ... /*Подвал*/
  • Отключение части CSS свойст при отладке (если вы хотите посмотреть как будет смотреться блок, если вы поменяете пару свойств, но при этом не хотите переписывать код заново, если вы решили вернуть всё как было, то целесообразно просто закоментировать необходимые CSS свойства)

    p{ /* color:red;Параграф красного цвета (было)*/ color:green;/*Параграф зеленого цвета (стало)*/ }

Коментарии в CSS увеличивают объем текста

Как вы понимаете, чем больше комментариев в CSS вы используете, тем более понятней становится ваш код и вам легче в нем ориентироваться. Но увеличение колличества символов в CSS файле влечет за собой увеличение размера файла, а следовательно сайт будет загружаться медленней. По этому комментарии используются только в процессе разработки и отладки. Когда верстка сайта готова, необходимо минимизировать CSS файл с помощью специальных сервисов, либо библиотек. В результате у вас будет 2 css файла.

  • Первый для работы
  • Второй для загрузки на сервер.

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

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

/* p { color: red; /* цвет текста в абзацах - красный */ background-color: green; } */

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

В каждом проекте есть определенные нюансы и тонкости, которые помнят далеко не все, и худшее, что может случиться с разработчиком — это работа с кодом, который писал не он. Даже запоминание тонкостей своего собственного кода является возможным только до определенной степени, не говоря уже о чужом коде. Именно поэтому 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. Именование классов Теги:

Почему комментарии в CSS важны?

Почему комментарии в CSS даже значительны? Я тестировал веб-сайт раньше и просто добавил текст после запятой:

#myId { property: value; this is my comment }

И никаких ошибок не было, значение все еще применялось к селектору, и все получилось просто отлично. Зачем использовать /* */? Я протестировал его в Chrome и Firefox, есть ли другие браузеры, которые могут не анализировать CSS, если я сделаю это, о чем я не знаю?

задан Jace Cotton 20 янв. '14 в 7:01

источник поделиться


Смотрите также



Компьютерные курсы по направлениям:

Для начинающих


A

Компьютер для начинающих: Word, Excel, Access и другие программы!

Графические пакеты


B

Популярные пакеты Adobe Photoshop, CorelDraw, ArchiCAD, AutoCAD и другие!

WEB + анимация


C

Курсы по созданию сайтов, WEB-дизайну и крутой анимации в Adobe Flash!

Бухгалтерия + делопроизводство

Сетевые технологии


E

Курсы сборки ПК, системных администраторов и защиты информации!