Комментирование CSS+HTML: стандарты, утилиты и т.п?

Question

[Антон]

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


Вопрос такой — есть ли нечто подобное для HTML/CSS?


Вопрос общий — подойдут и ссылки на стандарты/правила документирования, и ссылки на утилиты (если такие есть в природе), и просто ваши мысли и соображения на эту тему.


Цель — получить документацию по шаблонам и стилям на основании комментариев.

P.S. сам я не верстальщик, поэтому если вы — верстальщик и считаете, что идея бредовая — тоже пишите (желательно с объяснением причин)

Answer 1

[kaluzhanin]

Для CSS есть даже проект стандарта: cssdoc и его (неполная) имплементация на ruby: css_doc. Насколько это востребованно, не скажу, но логика подсказывает, что раз этим кто-то занимается, значит это кому-то нужно.

По HTML — информации не имею, да и не думаю, что это нужно. Все-таки в CSS можно указывать, когда применять данный стиль, а HTML говорит сам за себя.

Answer 2

[Виталий]

была статья по поводу cssdoc habrahabr.ru/blogs/css/87406/

Answer 3

[Андрей Билык]

Комментировать HTML — ИМХО бред. Код должен быть чистый. Другое дело — комментировать шаблоны (т.е. чтоб при рендеринге страницы все комменты удалялись и пользователям показывался чистый HTML)

CSS — аналогично, надо иметь 2 версии: 1-я форматированная, с комментами. 2-я (рабочая) — минимизированная (инструментов хватает) и, по возможности, сжатая.

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

Comments

[Антон]

Статью эту перед отправкой вопроса нашел, но там, на мой взгляд больше описывается взаимодействие дизайнер-верстальщик. А мой вопрос больше про верстальщик-верстальщик. Т.е. когда верстальщику надо будет поддерживать проект, сверстанный изначально кем-то другим.
Насчет комментирования HTML — например какой-то блок оказывается в неочевидном месте, стоит ли писать коментарий почему это было сделано и, если да — то как это лучше делать.
З.Ы. под HTML в моем вопросе я понимал именно шаблоны сайта.

[Андрей Билык]

Я при верстке пользую одно простое правило — верстать так, чтоб не возникало вопросов.
Но они, вопросы, конечно могут быть. Тут надо ориентироваться на шаблонизатор. В статье (в коментах) был дан пример со смарти — все коменты заключать в {* *}. В этом случае шаблонизатор сам будет чистить коменты перед выводом пользователю.