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
                      Я неясно выразился. Может иметь место такая ситуация, когда CSS для сайта расположен не в одной папке, а в разных, вместе с программным кодом и прочим, с разделением по модулям.
              • НЛО прилетело и опубликовало эту надпись здесь
                • 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/
                                                          */

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

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