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 <yes/no/true/false> — соответствует ли правило стандартам;
    Следующие в комментариях не нуждаются, но если кому-то будет непонятно, то можно посмотреть русскоязычную документацию к 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 <joe@shmoe.com>
    */

    /**
    * Это самый простой пример, поэтому используем самый
    * простой 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.

    Как пользоваться остальными тегами, думаю, понятно. Пользуйтесь этим и тогда настанет мир во всём мире всем будет намного удобнее.

    Кому интересно автодокументирование, то вот что получается в итоге.
    Поделиться публикацией
    Ой, у вас баннер убежал!

    Ну. И что?
    Реклама
    Комментарии 75
      –2
      Во, не знал что такая круть и для CSS есть :) Теперь буду пользовать :)
      • НЛО прилетело и опубликовало эту надпись здесь
          +2
          я посыаю луч ненависти в вашу сторону, как и другим, которые писали код как вы сказали, а я потом за ними этот код доделывал…
          зы: для ясности, я просто опроверг ваши слова, ело в том что после вас есть люди которые возможно будут ваш код дописывать, и если код хорошо откаментирован, и валиен, делать это приятней… то что он должен быть понятным и логичным, это итак ясно, я нарошно это упустил
            0
            какой мне прок от этого мусора?

            ну вот например «автор файла» — это что такое?! в один файл пишут несколько разработчиков и авторство кусков кода можно установить лишь по логам коммитов

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

            ну и так далее… от этой формализации никакого проку… жалкая попытка сделать «всё как у взрослых»
              +1
              > какой мне прок от этого мусора?
              ну к этоизму я же привык, это нормально, я как-то наваяю, а вы разгребайтесь

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

              и так даелее не катит, я вот например, очень уважаю такой стиль написания:
                  /**
                  * @desc
                  * @return Smarty
                  */
                  protected $view       = null;
              
                  /**
                  * @desc
                  * @return ADODB_mysql
                  */
                  private $_db        = null;
              


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

              в общем я не предлагаю следовать каждому шагу, а лишь говорю что некоторые части очень, нет, даже очень облегчают жизнь… как-то так
                –3
                сами себе придумали геморрой…

                пхп — это жёсткий оффтоп

                  0
                  неважно пхп это, руби или питон, для нетипизированных/слабо типизированных языков это полезное действие, да и помогает при разработке, может вы еще в одну строку пишете? я встречал людей которые даже табуляцию кода постоянно меняют, им пофигу было как писали код до них, они начинают табуляцию откуда им удобно… вообще я выше все написал, если вы считаете что это гемор, то это плохо :)
                    –1
                    любой язык программирования тут — жёсткий оффтоп
                      0
                      > думаю уже можно подводить итоги последнего исследования: местный контингент в массе своей не способен внимательно прочитать текст — большая половина так и не поняла о чём статья

                      не надо меряться пиписьками с другими, у вас отнюдь не больше в лушчем случае ;)
                        0
                        обоснуй
                          0
                          > это глубокий философский вопрос, разрешение которого сродни становлению новой формы мышления в условиях стагнирующей социальной системы, вырванной из обёртки высоколатентной комуникационной среды
                            –1
                            только и можешь, что как попугай повторять чужие глупости…
                              0
                              правда неприятно попадать под свои глупости? я веду к тому что люди могут ошибаться, никто ведь не заставляет использовать эту хрень, другое дело если его стандартизируют, некоторым будет удобно, дргие не будут использовать так же как и сейчас, это все делается по желанию, и если не хотите, не используйте
                                –1
                                мне неприятно общаться с идиотами — только и всего. вот ты сам будешь читать все эти коменты? только честно
                                  0
                                  смотря какие, я выше показал прекрасный пример фильтра док-ов, есть места где они пригодятся, идиотом будет человек, если он будет их применять не с умом а пихать везде где только можно
                                    –1
                                    например в css
                                      0
                                      я попробую еще раз обьяснить свое мнение, если и щас оно вам покажется глупым, тогда я даже не знаю что делать :)
                                      дело в том что сейчас каменты в цсс ставят, ставили и ставят, ставят где угодно, как кому угодно, и как кто захочет и в кто каком захочет стиле. так вот, каменты будут ставить и дальше, нравится ли вам это или нет, точно будут, и чтоб это не делалось кто как хочет, хотят ввести этот формат, они после этого просто приобретут одинаковый вид (это цель в идеале) а не будут в хаотических вариациях как сейчас (я сомневаюсь что все придерживаются одного стиля коментирования)
                                        0
                                        допустим мне надо прокомментировать какое-то свойство. предлагаешь перед этой строчкой добавить ещё 3 с комментом? когда комментов больше чем кода — собственно код воспринимать сложнее, ибо он теряет связность. комменты нужны лишь для тех случаев, когда выразительности языка не хватает
                                          0
                                          да, чтоб воспринималосль ничего сложней, люди используют редакторы с подсветкой, тогда каменты видны сразу и не отвлекают так сильно, еще их можно свернуть
                                            0
                                            подсветка не сильно помогает, ибо не решает проблему разрыва. и я не хочу каждый коммент вручную сворачивать и разворачивать. я хочу чтобы там _небыло_ мусора, который бы требовалось сворачивать
                                              0
                                              Всем никогда угодить не получится, я уверен, что есть ненавистники комментирования и кода на любых других языках. Не используйте, раз вам так удобнее, но и не ругайтесь потом на тех, кто вам даст код в «плохом» состоянии ; )
                                                0
                                                я регулярно ругаюсь на код с таким вот мусором =_="
                                                  0
                                                  Не сомневаюсь.
                                            0
                                            Инлайн комментарии никто не отменял + как ниже сказано подсветка обычно помогает, в большинстве редакоров по умолчанию комментарии бледнее основного кода.
                                              0
                                              инлайн комменты необходимы и достаточны
                    0
                    Руби, кстати, – строго типизированный язык. В данном случае следует говорить не о типизации, а об определении сигнатуры метода – там типы действительно не указываются, ибо могут быть любыми.
                      0
                      я это и имел ввид, просто неправильно вразился
                    0
                    А вы учитывает тот случай, что может не быть полного соответствия структур папок и ксс файлов? Что если всё разложено по модулям?
                      0
                      ну и чем модуль от пакета отличается?
                        0
                        Я неясно выразился. Может иметь место такая ситуация, когда CSS для сайта расположен не в одной папке, а в разных, вместе с программным кодом и прочим, с разделением по модулям.
                          0
                          ну и что? о0
                  • НЛО прилетело и опубликовало эту надпись здесь
                      0
                      я чуть выше описа что имел ввиду более подробно, возможно это как-то исправит шаблонную фразу
                    0
                    Если вы рассчитываете, чт оваш код никто никогда не будет поддерживать можно вообще писать хоть задом наперёд всё.
                    +2
                    размер файла * 10? ненене
                      +1
                      и? все равно на продакшн такую муть не выкладывают — пропускают через автоматику
                      • НЛО прилетело и опубликовало эту надпись здесь
                          0
                          с компактными файлами работать удобней. монитор не безграничен
                            0
                            тут речь не об этом. CSS/JS-файлы можно комментировать сколько и как душе угодно — все равно в продакшн должна уходить пожатая версия. И это должно быть правило. Вбитое так или иначе в головы разработчиков (не хотят делать сами — так пусть ставят хоть Minify, хоть WEBO Site SpeedUp).

                            Другое дело — когда комментарии в исполняемом серверном коде. Они, в принципе, на производительность не влияют, но размер пакета из-за них увеличивается. Было бы интересно услышать мнения, как можно готовить аналогичным образом (пред-компиляция, фактически) PHP (Perl / Python / ASP / Java / etc)-код к продакшену.
                              0
                              Shell-скриптом собираю классы в один файл и передаю zend encoder'у :)
                                –1
                                нет, и об этом тоже. просто ты помешан на оптимизации и других факторов даже не видишь :-Р
                                  0
                                  наверное, это был комплимент? :)

                                  просто исходный комментарий не в тему, вот я и возбух :)
                                    –1
                                    нет.

                                    вполне в тему. люблю когда файл помещается в экран — тогда его можно окинуть одним взглядом, а не создавать мозгу карту расположения частей файла
                                      0
                                      тут очень много факторов: когда работаешь один, то, может быть, удобнее работать с небольшим файлов. Если есть команда, то чем лучше обговорены правила игры, то тем всем удобнее (тут может быть удобнее как компактный вид, так и развернутый).

                                      Если же команда «плавающая», и приходят новые люди, то нужно, чтобы они быстро втягивались, нужен стандарт для процесса разработки. Тут как раз такие комментарии будут намного «удобнее», чем «все в одну строку».

                                      Поскольку рассматривать размер файла с точки зрения удобства разработки (объективно) нельзя, то его можно рассматривать только с точки зрения клиентской оптимизации, нет?
                                        –1
                                        есть большая разница между «коментарием поясняющим неочевидный код» и «какой-то мусор, который никто не читает»
                                          0
                                          ну, когда команда человек десять, то разницы почти нет. Серьезно :)
                                            –1
                                            зависит от квалификации разумеется…
                          • НЛО прилетело и опубликовало эту надпись здесь
                            +1
                            Язык программирования комментариев
                            • НЛО прилетело и опубликовало эту надпись здесь
                                0
                                Скорее разметки.
                                • НЛО прилетело и опубликовало эту надпись здесь
                                  0
                                  ждем формат комментариев для языка программирования комментариев =)
                                  0
                                  А еще можно пользоваться старым проверенным Doxygen (пример проект), слегка его допилив.
                                    0
                                    CSS это уже описание само по себе.
                                    Только название давать понятные.
                                    Комментарии то в отличи от комментариев в PHP не удаляются и зачем на CSS распухший от комментариев.

                                      +2
                                      «Проект отлично документирован на С++»
                                      +2
                                      Мне кажется, это не только очень полезная штука, но признак хорошего тона
                                      • НЛО прилетело и опубликовало эту надпись здесь
                                        • НЛО прилетело и опубликовало эту надпись здесь
                                            0
                                            Похоже вы чего-то не понимаете. Заказчкик будет рад, если всё будет сделано так, чтобы потом кто-то другой смог во всём проще и быстрее разобраться
                                              0
                                              Если вы имеете ввиду сроки, то я вас понимаю, но не думаю, что комментарии в коде займут уж слишком много времени. В конце-то концов, никто не требует от вас написать целый роман
                                            0
                                            По моему вместо section и так далее проще разделять большой CSS-файл на подфайлы (reset.css, menu.css, ie.css), а потом собирать сборщиком (удаляя лишние проблемы, комментарии и сжимая в gz). В общем, такие комментарии — излишнее усложнение задачи.
                                              0
                                              Вы не учитываете случае, когда всё-таки нужно сделать разделение внутри файлов. Если вам этого не приходилось делать — это не значит, что не приходилось другим людям
                                              +1
                                              Вспоминается венгерская нотация ;) И где она сейчас, кто-нибудь помнит?
                                                0
                                                Спасибо. Совсем недавно читал подобное на английском, но потерял линк на материал. Очень кстати.
                                                  +1
                                                  у вас опечатка в имени тэга @subsection
                                                    0
                                                    Я не понимаю смысл комментировать css. Это же стили, зачем их комментировать?
                                                    Когда мне что-то нужно найти я запускаю Firebug и смотрю строчку в файле стилей.
                                                    То что font-size:150% — увеличивает шрифт в полтора раза понятно и без комментариев.

                                                    Самое главное это не смешивать таблицы с блоками, таблицами вообще не верстать и правильно обзывать классы и идентификаторы, чтобы не было там наборов букв для дешифровальной машины…

                                                    Всё остальное… извольте… это лишне…

                                                    Не преумножайте сущности без необходимости
                                                      0
                                                      Понятно, что в КО никто записываться вас не просит — это как раз дурной тон комментирования : ) Но бывают всякие нетривиальные вещи и тогда это полезно.
                                                      0
                                                      Хмм… 50 на 50. С одной стороны наглядность, и в то же время CSSDoc увеличивает затраты времени и сил на оптимизацию кода после отладки. Сделал для себя вывод: пользоваться буду, но только на стадии разработки и если я не один работаю, а в команде.
                                                        0
                                                        Ну когда в нашей компании будет очень, ОЧЕНЬ много больших и сложноструктурированных проектов, то тут CSSDoc очень сильно пригодится. А пока что нам достаточно писать простой, понятный и логичный CSS с комментированием сложных или непонятных мест (каких в большинстве случаев немного).
                                                          0
                                                          В принципе я подобными проектами и занимаюсь, поэтому вещи написанные мной для меня очевидны, но для большинства почему-то нет.
                                                          0
                                                          Комментировать код конечно хорошо, но, ИМХО, xdoc служит скорее для генерации документации по исходниками, а не комментирования кода как такового.
                                                            0
                                                            В этот раз я не хотел затрагивать этот момент. Я даже написал об этом : )
                                                            0
                                                            я поддерживаю автора, хот что то. А то как возьмешь проект на доделку, не то что коментов нет но именование просто жуть. а хоть какой то стандарт упростил работу.
                                                              0
                                                              Не помню откуда я это взял, но уже давненько пишу в своих css файлах следующее:
                                                              /*
                                                               @Author Sytrus
                                                               @url http://mysite.ru/
                                                              */

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

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

                                                              Самое читаемое