Pull to refresh

Comments 27

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

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

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

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

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

Наверное, веб-технологи и верстальщики, те кому приходится много работать с шаблонами, подтвердят мои слова.
На это я каждый день смотрю, а хотелось на пример обработки smarty шаблонов… интересно что будет в результирующих файлах от реальных шаблонов.
Пользовался doxygen для этих целей, очень удобно
Комментировал только в местах, где использовалась нетривиальная разметка, а так как-то даже не было мысли, что такое может понадобиться
Согласен, имхо за правило надо принимать, что комменты обязательно должны предшествовать
нетривиальным местам и костылям любой природы.
1. Понадобится может, когда разработчиков больше одного.
2. И еще не редко бывает — одни разработчики сменяют других.
Обычно получается, что одна вьюшка — один шаблон. Соответственно документацию беру из кода вьюшки — смотрю что передаю в шаблон. Куда актуальнее, чем документировать в шаблоне «в лоб» — очень быстро устаревает.
тогда надо верстальщиков учить читать код-вьюхи
А зачем придуманы {debug} в smarty и делающие то же самое dump-* в blitz?
Делается специальный отдалочный режим для дизайнеров — и все.

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

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

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

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

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

Ps: Не всякой команде и не всякой программе/продукту нужны доки. (не только шаблонные)
суть моего утверждения была в том, что в рамках своей команды может быть сколько угодно своих спецификаций, которые можно применять на своих собственных проектах. С другой стороны если поддержка сайта может перейти к людям, у которых своя другая система документирования или т.п., это не должно применяться, имхо.
Т.е. Вы считаете, что документация новой командой разработчиков будет непонята (потому что у них своя система документирования), вырезана и забыта, а все переменные в шаблонах будут изучаться заново?
нет конечно, просто шаблоны будут пестрить. ведь есть же стандарты написания кода, регламентирующие, например, всякие оступы, скобочки и т.д.
Смысл не меняется, а удобство теряется (при различии стандартов)
Никто не умрёт. А, если не делать движений в эту сторону и ждать, что кто-то сделает стандарт и все начнут его использовать, то можно и не дождаться.
гораздо хуже, когда проект переходит другой команде и не содержит документации вообще
как минимум не помешает написать автора шаблона, принадлежность к модулю

описание массивов тоже прекрасная практика
Я лично не встречал шаблоны в которых нужно было разбираться. Может ваши шаблоны через чур громоздки? Тогда стоит их дробить на составляющие.
Дробим, но получается каталог шаблонов модуля с кучей файлов, до 20 шт.
И при таком кол-ве по названию шаблона не всегда можно догадаться где используется и для чего нужен.
Sign up to leave a comment.

Articles