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

[DoctorMozg]

Во, не знал что такая круть и для CSS есть :) Теперь буду пользовать :)

[taliban]

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

[tenshi]

какой мне прок от этого мусора?

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

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

ну и так далее… от этой формализации никакого проку… жалкая попытка сделать «всё как у взрослых»

[taliban]

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

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

и так даелее не катит, я вот например, очень уважаю такой стиль написания:

    /**
    * @desc
    * @return Smarty
    */
    protected $view       = null;

    /**
    * @desc
    * @return ADODB_mysql
    */
    private $_db        = null;

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

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

[tenshi]

сами себе придумали геморрой…

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

[taliban]

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

[tenshi]

любой язык программирования тут — жёсткий оффтоп

[taliban]

> думаю уже можно подводить итоги последнего исследования: местный контингент в массе своей не способен внимательно прочитать текст — большая половина так и не поняла о чём статья

не надо меряться пиписьками с другими, у вас отнюдь не больше в лушчем случае ;)

[tenshi]

обоснуй

[taliban]

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

[tenshi]

только и можешь, что как попугай повторять чужие глупости…

[taliban]

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

[tenshi]

мне неприятно общаться с идиотами — только и всего. вот ты сам будешь читать все эти коменты? только честно

[taliban]

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

[tenshi]

например в css

[taliban]

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

[tenshi]

допустим мне надо прокомментировать какое-то свойство. предлагаешь перед этой строчкой добавить ещё 3 с комментом? когда комментов больше чем кода — собственно код воспринимать сложнее, ибо он теряет связность. комменты нужны лишь для тех случаев, когда выразительности языка не хватает

[taliban]

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

[tenshi]

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

[ArtyV]

Всем никогда угодить не получится, я уверен, что есть ненавистники комментирования и кода на любых других языках. Не используйте, раз вам так удобнее, но и не ругайтесь потом на тех, кто вам даст код в «плохом» состоянии ; )

[tenshi]

я регулярно ругаюсь на код с таким вот мусором =_="

[ArtyV]

Не сомневаюсь.

[ArtyV]

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

[tenshi]

инлайн комменты необходимы и достаточны

[edelweard]

Руби, кстати, – строго типизированный язык. В данном случае следует говорить не о типизации, а об определении сигнатуры метода – там типы действительно не указываются, ибо могут быть любыми.

[taliban]

я это и имел ввид, просто неправильно вразился

[ArtyV]

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

[tenshi]

ну и чем модуль от пакета отличается?

[ArtyV]

Я неясно выразился. Может иметь место такая ситуация, когда CSS для сайта расположен не в одной папке, а в разных, вместе с программным кодом и прочим, с разделением по модулям.

[tenshi]

ну и что? о0

[taliban]

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

[ArtyV]

Если вы рассчитываете, чт оваш код никто никогда не будет поддерживать можно вообще писать хоть задом наперёд всё.

[Nesp]

размер файла * 10? ненене

[sunnybear]

и? все равно на продакшн такую муть не выкладывают — пропускают через автоматику

[tenshi]

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

[sunnybear]

тут речь не об этом. CSS/JS-файлы можно комментировать сколько и как душе угодно — все равно в продакшн должна уходить пожатая версия. И это должно быть правило. Вбитое так или иначе в головы разработчиков (не хотят делать сами — так пусть ставят хоть Minify, хоть WEBO Site SpeedUp).

Другое дело — когда комментарии в исполняемом серверном коде. Они, в принципе, на производительность не влияют, но размер пакета из-за них увеличивается. Было бы интересно услышать мнения, как можно готовить аналогичным образом (пред-компиляция, фактически) PHP (Perl / Python / ASP / Java / etc)-код к продакшену.

[Proxmiff]

Shell-скриптом собираю классы в один файл и передаю zend encoder'у :)

[tenshi]

нет, и об этом тоже. просто ты помешан на оптимизации и других факторов даже не видишь :-Р

[sunnybear]

наверное, это был комплимент? :)

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

[tenshi]

нет.

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

[sunnybear]

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

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

Поскольку рассматривать размер файла с точки зрения удобства разработки (объективно) нельзя, то его можно рассматривать только с точки зрения клиентской оптимизации, нет?

[tenshi]

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

[sunnybear]

ну, когда команда человек десять, то разницы почти нет. Серьезно :)

[tenshi]

зависит от квалификации разумеется…

[ferasinka]

Язык программирования комментариев

[ChemAli]

Скорее разметки.

[deniamnet]

ждем формат комментариев для языка программирования комментариев =)

[sidristij]

А еще можно пользоваться старым проверенным Doxygen (пример проект), слегка его допилив.

[conturov]

CSS это уже описание само по себе.
Только название давать понятные.
Комментарии то в отличи от комментариев в PHP не удаляются и зачем на CSS распухший от комментариев.

[bolk]

«Проект отлично документирован на С++»

[sarlv]

Мне кажется, это не только очень полезная штука, но признак хорошего тона

[ArtyV]

Похоже вы чего-то не понимаете. Заказчкик будет рад, если всё будет сделано так, чтобы потом кто-то другой смог во всём проще и быстрее разобраться

[sarlv]

Если вы имеете ввиду сроки, то я вас понимаю, но не думаю, что комментарии в коде займут уж слишком много времени. В конце-то концов, никто не требует от вас написать целый роман

[Iskin]

По моему вместо section и так далее проще разделять большой CSS-файл на подфайлы (reset.css, menu.css, ie.css), а потом собирать сборщиком (удаляя лишние проблемы, комментарии и сжимая в gz). В общем, такие комментарии — излишнее усложнение задачи.

[ArtyV]

Вы не учитываете случае, когда всё-таки нужно сделать разделение внутри файлов. Если вам этого не приходилось делать — это не значит, что не приходилось другим людям

[pvasili]

Вспоминается венгерская нотация ;) И где она сейчас, кто-нибудь помнит?

[anotherpit]

у вас опечатка в имени тэга @subsection

[bRuz]

Я не понимаю смысл комментировать css. Это же стили, зачем их комментировать?
Когда мне что-то нужно найти я запускаю Firebug и смотрю строчку в файле стилей.
То что font-size:150% — увеличивает шрифт в полтора раза понятно и без комментариев.

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

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

Не преумножайте сущности без необходимости

[ArtyV]

Понятно, что в КО никто записываться вас не просит — это как раз дурной тон комментирования : ) Но бывают всякие нетривиальные вещи и тогда это полезно.

[yuhenobi]

Хмм… 50 на 50. С одной стороны наглядность, и в то же время CSSDoc увеличивает затраты времени и сил на оптимизацию кода после отладки. Сделал для себя вывод: пользоваться буду, но только на стадии разработки и если я не один работаю, а в команде.

[GruZZ]

Ну когда в нашей компании будет очень, ОЧЕНЬ много больших и сложноструктурированных проектов, то тут CSSDoc очень сильно пригодится. А пока что нам достаточно писать простой, понятный и логичный CSS с комментированием сложных или непонятных мест (каких в большинстве случаев немного).

[ArtyV]

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

[AndrewStephanoff]

Комментировать код конечно хорошо, но, ИМХО, xdoc служит скорее для генерации документации по исходниками, а не комментирования кода как такового.

[ArtyV]

В этот раз я не хотел затрагивать этот момент. Я даже написал об этом : )

[bo883]

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

[Sytrus]

Не помню откуда я это взял, но уже давненько пишу в своих css файлах следующее:

/*
 @Author Sytrus
 @url http://mysite.ru/
*/

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