Comments 27
Пример бы результирующего документа разместил бы где-то…
0
ИМХО возможность сгенерить HTML-доки это бонус. Главная фишка встроенной документации —
это то, что мы видим доку непосредственно при работе с кодом.
Вот, посмотрите доку от ZendFramework: framework.zend.com/apidoc/1.10/
Она есть, но гораздо удобнее юзать референс: framework.zend.com/manual/en/
А когда мы работаем с кодом редакторе или ide тут и проявляется сила встроенной документации. :)
Некоторые IDE умеют подсказывать при наличии доков (к сожалению, к шаблонам это пока не относится).
Просто тот факт, что при открытии шаблона сразу видно какие данные туда передаются
уже снимает много вопросов.
Наверное, веб-технологи и верстальщики, те кому приходится много работать с шаблонами, подтвердят мои слова.
это то, что мы видим доку непосредственно при работе с кодом.
Вот, посмотрите доку от ZendFramework: framework.zend.com/apidoc/1.10/
Она есть, но гораздо удобнее юзать референс: framework.zend.com/manual/en/
А когда мы работаем с кодом редакторе или ide тут и проявляется сила встроенной документации. :)
Некоторые IDE умеют подсказывать при наличии доков (к сожалению, к шаблонам это пока не относится).
Просто тот факт, что при открытии шаблона сразу видно какие данные туда передаются
уже снимает много вопросов.
Наверное, веб-технологи и верстальщики, те кому приходится много работать с шаблонами, подтвердят мои слова.
0
Пользовался doxygen для этих целей, очень удобно
0
Результаты у него не особо презентабельные.
0
Комментировал только в местах, где использовалась нетривиальная разметка, а так как-то даже не было мысли, что такое может понадобиться
+6
Согласен, имхо за правило надо принимать, что комменты обязательно должны предшествовать
нетривиальным местам и костылям любой природы.
нетривиальным местам и костылям любой природы.
-1
1. Понадобится может, когда разработчиков больше одного.
2. И еще не редко бывает — одни разработчики сменяют других.
2. И еще не редко бывает — одни разработчики сменяют других.
-1
Ну у меня обе ситуации присутствуют, поэтому я писал о документировании CSS. Здесь же мне непонятно, что это даёт
0
Обычно получается, что одна вьюшка — один шаблон. Соответственно документацию беру из кода вьюшки — смотрю что передаю в шаблон. Куда актуальнее, чем документировать в шаблоне «в лоб» — очень быстро устаревает.
+2
Сталкиваетесь ли с тем, что шаблоны становятся очень громоздкими и сложными?
0
хм, а какое дело шаблону, откуда взялась та или иная переменная? если я меняю, скажем, контроллер таким образом, что некая переменная $list заполняется иным методом а то и классом, то нужно зайти и переписать комментарий в шаблоне? Имхо — это от нехер делать у вас появилось в конторе, либо от излишней логики в них. Именно потому что шаблон — это всего-лишь шкурка-обертка для вывода данных — она простая как двери и комментировать там впринципе нечего.
+3
Нет, шаблоны не документирую, так как не знаю форматов. То, что вы предлагаете — это ваше изобретение, а не спецификация.
ЗЫ. Не так давно на хабре обсуждался CSSDoc (в стадии черновика). Аналогичная история, но тут хотя бы есть намёк на стандартизацию (в будущем).
ЗЫ. Не так давно на хабре обсуждался CSSDoc (в стадии черновика). Аналогичная история, но тут хотя бы есть намёк на стандартизацию (в будущем).
+1
Отсутствие спецификации — это не препятствие.
Дока, которую мы используем для документирования php — изобретение команды разработчиков
phpDocumentor, которые скопировали ее из встроенной документации java
А спецификации то нет :)
Если вы считаете, что документация поможет вам работать — почему не принять свой стандарт.
Ps: Не всякой команде и не всякой программе/продукту нужны доки. (не только шаблонные)
Дока, которую мы используем для документирования php — изобретение команды разработчиков
phpDocumentor, которые скопировали ее из встроенной документации java
А спецификации то нет :)
Если вы считаете, что документация поможет вам работать — почему не принять свой стандарт.
Ps: Не всякой команде и не всякой программе/продукту нужны доки. (не только шаблонные)
-2
суть моего утверждения была в том, что в рамках своей команды может быть сколько угодно своих спецификаций, которые можно применять на своих собственных проектах. С другой стороны если поддержка сайта может перейти к людям, у которых своя другая система документирования или т.п., это не должно применяться, имхо.
0
Т.е. Вы считаете, что документация новой командой разработчиков будет непонята (потому что у них своя система документирования), вырезана и забыта, а все переменные в шаблонах будут изучаться заново?
+1
нет конечно, просто шаблоны будут пестрить. ведь есть же стандарты написания кода, регламентирующие, например, всякие оступы, скобочки и т.д.
Смысл не меняется, а удобство теряется (при различии стандартов)
Смысл не меняется, а удобство теряется (при различии стандартов)
0
гораздо хуже, когда проект переходит другой команде и не содержит документации вообще
0
как минимум не помешает написать автора шаблона, принадлежность к модулю
описание массивов тоже прекрасная практика
описание массивов тоже прекрасная практика
+3
Я лично не встречал шаблоны в которых нужно было разбираться. Может ваши шаблоны через чур громоздки? Тогда стоит их дробить на составляющие.
0
Sign up to leave a comment.
Документирование шаблонов