Документирование interface в PHP проектах?

[confguru]

Документирование interface в PHP проектах?

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

interface iTemplate
{
    /**
     * Enter description here...
     *
     * @param unknown_type $name
     * @param unknown_type $var
     */
    public function setVariable($name, $var);
    /**
     * Enter description here...
     *
     * @param unknown_type $template
     */
    public function getHtml($template);
}

Это описание редактор не подхватывает, а подхватывает только из имплементации.
Единственно что может помочь - при создании класса на основе интерфейса
можно скопипастить описание чтоб редактор подсвечивал

 

[c0dex]

Я обычно не документирую, если потом идет документация по методу в импелментации, как раз из-за того, что нет подсветки автоматом. Хотя с моими понятными названиями методой обычно и доки не сильно нужны.

 

[FB3]

ИМХО, стоит писать. Zend Studio подхватывает к примеру.

 

[shureen]

У меня чёт не подхватывает Zend Studio (7.0.1) нифига, приходится так же дублировать

 

[FB3]

shureen
У меня 7.2.0 Build ID: 20100421

А что вообще мы имеем ввиду под подхватыванием? Всплывающую подсказку, которая выводит инфу о методе, которую мы прописали в PHPDOC? Тогда точно подхватывает у меня

 

[weregod]

NuSphere phpEd 5.9 тоже не подхватывает, но сам phpDocumentor подхватит по-любому

 

[AmdY]

нетбинс тоже подхватывает

 

[confguru]

Автор оригинала: FB3
shureen
У меня 7.2.0 Build ID: 20100421

А что вообще мы имеем ввиду под подхватыванием? Всплывающую подсказку, которая выводит инфу о методе, которую мы прописали в PHPDOC? Тогда точно подхватывает у меня

Попробуй в разных файликах разместить интерфейс и имплементацию.

 

[Long]

однозначно нужно - часто в качестве "типа" приходится указывать интерфейс, и тогда студия не найдет определений

 

[fixxxer]

однозначно нужно

в интерфейсе описывается что должно реализовываться

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

проблемы реализаций иде не должны влиять на семантику и здравый смысл

 

[Long]

fixxxer как раз если руководствоваться здравым смыслом, то не стоит, ибо "если что-то нуждается в комментировании, то это на 99% стоит переписать". да и поддержка актуальности большого и подробного комментария вызывает большие сомнения. лучше в тестах это отразить

 

[newARTix]

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

Хотя этот вопрос меня вообще давно интересует Интерфейс этот такой сферический конь в вакууме, какой от него реальный толк?

 

[fixxxer]

Long
да зачем большие? "implementation must bla bla bla" и только там, где возможны неочевидности.

как ты себе представляешь тест на интерфейс?

-~{}~ 26.08.10 02:10:

newARTix

типизация вида "я умею то-то". Например, все что угодно может быть datasource-ом и передаваться аргументом; принимающий же знает в этом случае, что оно умеет, положим, has($key) и get($key).

 

[Long]

fixxxer
>как ты себе представляешь тест на интерфейс?
>в классе, его реализующем, возможно, детали конкретной реализации
ты сам сообщением раньше ответил на свое сообщение из будщего

 

[whirlwind]

newARTix
там где тестируется реализация интерфейса - тест под интерфейс
там где тестируется пользователь интерфейса - интерфейс под тест (мок на интерфейс лучше мока на класс)

-~{}~ 26.08.10 06:29:

ЗЫ. Тест на интерфейс

function testInterface() {
    $obj = new MySuppaDuppaClass();
    $this->assertType('ISuppaDuppa', $obj);
}

 

[fixxxer]

>> мок на интерфейс лучше мока на класс

а интересный подход, возьму на вооружение

-~{}~ 26.08.10 06:29:

 

[Здыхлик]

Автор оригинала: Long
fixxxer ибо "если что-то нуждается в комментировании, то это на 99% стоит переписать". да и поддержка актуальности большого и подробного комментария вызывает большие сомнения.

Да ладно? Комментарии для лохов? Хорошее документирование зачастую помогает не лазить в различного рода мануалы и API. Особенно если код смотрит не его разработчик.

 

[Alexandre]

нужно, я документирую

 

[whirlwind]

А что комментировать в setVar($name, $value) ? какая конкретно часть непонятна? set, var, name или value? Вот если бы там было sv($a, $b) вот тогда другое дело. Хороший интерфейс не нуждается в комментариях, если на буквах не экономить. Единственный минус (пыха) - отсутствие retval в прототипе.

 

[Здыхлик]

А что мешает не экономить на буквах вообще, что в самом коде, что на его комментировании? Тем более, что помимо цели метода можно описать ожидаемые типы данных для параметров и возвращаемого результата и т.д. Проще написать комментарий сразу, потратив на это одну минуту, чем через месяц уныло прокручивать подзабытый код.

Согласен, с интерфейсами все не так сложно и запущено, как с обычными классам. Но все же - я за документирование. Как минимум, это дисциплинирует ))