Документирование шаблонов

[mecommayou]

Пример бы результирующего документа разместил бы где-то…

[agorlov]

ИМХО возможность сгенерить HTML-доки это бонус. Главная фишка встроенной документации —
это то, что мы видим доку непосредственно при работе с кодом.

Вот, посмотрите доку от ZendFramework: framework.zend.com/apidoc/1.10/
Она есть, но гораздо удобнее юзать референс: framework.zend.com/manual/en/

А когда мы работаем с кодом редакторе или ide тут и проявляется сила встроенной документации. :)

Некоторые IDE умеют подсказывать при наличии доков (к сожалению, к шаблонам это пока не относится).

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

Наверное, веб-технологи и верстальщики, те кому приходится много работать с шаблонами, подтвердят мои слова.

[mecommayou]

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

[tsippa]

Пользовался doxygen для этих целей, очень удобно

[mecommayou]

Результаты у него не особо презентабельные.

[ArtyV]

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

[agorlov]

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

[agorlov]

1. Понадобится может, когда разработчиков больше одного.
2. И еще не редко бывает — одни разработчики сменяют других.

[ArtyV]

Ну у меня обе ситуации присутствуют, поэтому я писал о документировании CSS. Здесь же мне непонятно, что это даёт

[casey]

Обычно получается, что одна вьюшка — один шаблон. Соответственно документацию беру из кода вьюшки — смотрю что передаю в шаблон. Куда актуальнее, чем документировать в шаблоне «в лоб» — очень быстро устаревает.

[agorlov]

тогда надо верстальщиков учить читать код-вьюхи

[casey]

А зачем придуманы {debug} в smarty и делающие то же самое dump-* в blitz?
Делается специальный отдалочный режим для дизайнеров — и все.

&SMARTY_DEBUG=1 и &BLITZ_DEBUG=1 в моем случае

[MTonly]

Сталкиваетесь ли с тем, что шаблоны становятся очень громоздкими и сложными?

Мух и котлет Бизнес-логику и шаблоны держу раздельно.

[agorlov]

мы тоже, но оказывается иногда бывает и много логики-представления

[ferrari]

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

[agorlov]

Надуманно имхо по некую переменную $list.

Пример: шаблон для вывода постов не предназначен для вывода комментов так как
набор данных передаваемых в посты будет отличаться от данных для вывода комментов.

[piumosso]

Нет, шаблоны не документирую, так как не знаю форматов. То, что вы предлагаете — это ваше изобретение, а не спецификация.
ЗЫ. Не так давно на хабре обсуждался CSSDoc (в стадии черновика). Аналогичная история, но тут хотя бы есть намёк на стандартизацию (в будущем).

[agorlov]

Отсутствие спецификации — это не препятствие.

Дока, которую мы используем для документирования php — изобретение команды разработчиков
phpDocumentor, которые скопировали ее из встроенной документации java

А спецификации то нет :)

Если вы считаете, что документация поможет вам работать — почему не принять свой стандарт.

Ps: Не всякой команде и не всякой программе/продукту нужны доки. (не только шаблонные)

[piumosso]

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

[sectus]

Т.е. Вы считаете, что документация новой командой разработчиков будет непонята (потому что у них своя система документирования), вырезана и забыта, а все переменные в шаблонах будут изучаться заново?

[piumosso]

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

[sectus]

Никто не умрёт. А, если не делать движений в эту сторону и ждать, что кто-то сделает стандарт и все начнут его использовать, то можно и не дождаться.

[agorlov]

гораздо хуже, когда проект переходит другой команде и не содержит документации вообще

[piumosso]

ну, это верно, конечно…

[bur_i]

как минимум не помешает написать автора шаблона, принадлежность к модулю

описание массивов тоже прекрасная практика

[Zarohan]

Я лично не встречал шаблоны в которых нужно было разбираться. Может ваши шаблоны через чур громоздки? Тогда стоит их дробить на составляющие.

[agorlov]

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