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

    Документация — это хорошо! Она позволяет экономить время, и гармонично работать людям в команде. Встроенная в код документация — вдвойне хороша, она находится там где она нужна и не надо далеко ходить чтобы ее написать.

    Под катом пара наглядных примеров документации к шаблонам.




    В наших собственных проектах мы пишем встроенные доки к исходному коду (phpDocumentor), но
    почему-то шаблоны игнорируем, а ведь это так просто!

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

    Добавив такие доки, можно сэкономить время верстальщиков и собственное.

    Пример 1: шаблон list.tpl

    {* 
      Список постов
     
      Используется в: BlogModule::listAction 
      Передаваемые переменные:
        $returnedInfo array посты [ { id : 447, title : 'тайтл', ...}
      ]
        $pager AE_Pager объект постраничной навигации
        $admin boolean админ/не админ
        $years array [2010,2009,2008]
        $months array { апрель : 4, март : 3, февраль : 2 }
        $selectedYear год или null (если "Все")
        $selectedMonth месяц или null (если "Все")
    *}
     
    {if $admin}
      <button class="button" onClick="window.location='/{$SECTION}/addNews'">Добавить запись</button>
    {/if}
     
    {foreach key=cid item=con from=$returnedInfo}

    {/foreach}


    Пример 2: в нотации phpDocumentor:
    {* 
      Список постов
     
      Особенности и нюансы, примечания и другие подробности в этом абзаце
      @see BlogModule::listAction 
      @param array $returnedInfo посты [ { id : 447, title : 'тайтл' }
     ]
      @param AE_Pager $pager  объект постраничной навигации
      @param boolean $admin админ/не админ
      @param array $years [2010,2009,2008]
      @param array $months { апрель : 4, март : 3, февраль : 2 }
      @param mixed $selectedYear год или null (если "Все")
      @param mixed $selectedMonth месяц или null (если "Все")
    *}
     
     
    {if $admin}
      <button class="button" onClick="window.location='/addNews'">Добавить запись</button>
    {/if}
     
    {foreach key=cid item=con from=$returnedInfo}

    {/foreach}


    Как правильно документировать массивы



    Есть еще одна проблема: phpDocumentor не говорит в каком виде писать доку к массивам,
    и разработчики не редко игнорируют ее:
       @param array $returnedInfo массив постов
    


    Не очень информативно, согласитесь?

    Для себя, я решил, что удобно в доке приводить пример массива в JSON нотации:
      @param array $years [2010,2009,2008]
      @param array $months { апрель : 4, март : 3, февраль : 2 }
    


    Почему JSON? Потому что компактнее, и для меня читабельнее.

    Как вариант, могу предложить синтаксис PHP:
      @param array $years array(2010,2009,2008)
      @param array $months  array( 'апрель' => 4, 'март' => 3, 'февраль' => 2 )
    


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

    Похожие публикации

    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 27

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

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

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

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

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

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

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

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

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

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

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

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

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

                        Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                        Самое читаемое