какую документацию я использую

[Alexandre]

какую документацию я использую

собственно, хочу услышать мнения

 

[baev]

Какая-то мешанина...

Пожалуй, начать стоит вот с чего:
Alexandre, что Вы понимаете под «документацией»?

 

[fixxxer]

согласен с baev, но вроде бы понял, о чем вопрос, потому, не тыкая в галочки, отвечу как понял.

что касается изначальной постановки задачи - то это некий design document, представленный в виде текстовой странички в wiki и, если применимо, предварительным макетом в png.
процесс разработки - тикеты, по мере разработки важная информация из тикетов копируется в вики.
описание архитектуры и функционала важных пакетов (т.е. с которыми работает более чем 1 человек) делется тоже в вики.
всякие phpDoc считаю злом и засорением исходников, комментарии пишутся в начале пакета если это нужно, ну и там, где они действительно нужны.

 

[Krishna]

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

Я уже высказывался по этому поводу, но хочу развернуть вопрос
Мне думается, что основная польза от phpdoc каментов проявляется в полноценных IDE навроде Eclipse или Zend.

Во-первых, там их добавление максимально автоматизировано и упрощено, то есть фактически затраты на их "набивание" абсолютно копеечные. Он так же обычно по дефолту сворачиваются и не мозолят глаз. Ну и используются самим IDE как для вывода подсказок по пользовательским функциям, так и, что гораздо существеннее, для функции autocomplete. То есть, если для метода класса, возращающего как результат объект другого класса прописан @return в каменте - это учитывается IDE и позволяет использовать его в автокомплите.

Это только те полезности, о которых я в курсе, может еще что-то есть)

З.Ы. Да и по-моему, вообще хорошо, когда имеется общий формат каментов кода.
Но я хочу подчеркнуть, что речь не идет о том, что обязательно покрывать комментариями 100% методов и классов.

Вообще, долой религиозную нетерпимость во всех её проявлениях

 

[Alexandre]

что Вы понимаете под «документацией»?

http://ru.wikipedia.org/wiki/Техническая_документация

Техническая документация — набор документов, используемых при проектировании (конструировании), создании (изготовлении) и использовании (эксплуатации) каких-либо технических объектов: зданий, сооружений, промышленных товаров, программного и аппаратного обеспечения

Документация на программное обеспечение

Типы документации
Существует четыре основных типа документации на ПО:

архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО
техническая — документация на код, алгоритмы, интерфейсы, API
пользовательская — руководства для конечных пользователей, администраторов системы и другого персонала
маркетинговая

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

 

[fixxxer]

Krishna
я признаться не понимаю почему всякие эти навороченные ide не могут строить автокомплит прямо по исходникам. ну я тебе покажу как я работаю в vim. видимо просто разные подходы

Alexandre
ну вот уж пользовательская документация меня вообще не волнует =)
а архитектурная и техническая документация это на самом деле очень сильно взаимосвязанные вещи.

 

[atv]

всякие phpDoc считаю злом и засорением исходников

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

Удобство phpDoc ещё в том, что Zend Studio его понимает, и можно использовать автоподстановку.

 

[Krishna]

fixxxer
Они могут, если у тебя, например, переменная определённого класса объявлена в пределах текущей видимости.
А если у тебя что-то вроде

$secret_value  = $someClassObject->thisMethodReturnsSomeUnknownObject();
$secret_value->  // - < вот здесь, например PDT сядет в лужу, если у метода thisMethodReturnsSomeUnknownObject() не будет прописан камент:

/**
* @return WellKnownClass 
**/

 

[fixxxer]

atv
а я называю методы и аргументы так, что и без комментариев все понятно.
в vim с включенным folding очень удобно смотреть именно исходники.

 

[atv]

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

И как ты их называешь, что бы было понятно, что метод в определённых случаях бросает исключение?

 

[fixxxer]

исключения все именованные и прописываются в начале пакета в виде
class DbQueryException extends Exception;
по именам понятно где оно бросается.
разумеется, в случаях, когда что-то сходу непонятно, прямо над объявлением метода пишется комментарий в произвольном виде.
ну и я не пользуюсь никакими ide, они мне неудобны, так что все разговоры типа "а вот там в zend/eclipse" меня не волнуют.

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

 

[atv]

и не надо устраивать холиваров, я ничего не пропагандирую

Сам виноват Незачем было так высказываться:

всякие phpDoc считаю злом и засорением исходников

 

[Alexandre]

интересно, а составление ChangeLog как-то можно автоматизировать?

 

[fixxxer]

если принять соглашения по написанию commit messages то запросто
еще вариант - из багтрекера

 

[atv]

интересно, а составление ChangeLog как-то можно автоматизировать?

SVN позволяет получать историю коммитов в XML формате, и где-то в инете я находил XSL шаблон для преобразования его в ChangeLog.

 

[Luerssen]

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

Но Техническое Задание от заказчиков всегда требуем.

Почему так всё туго? А у нас не туго Строго принятые стандарты кода, за нарушение которых вручаем штрафы.

Как сказал мой дед: "Грязно не там — где убирают, а там — где не срут."

 

[fixxxer]

ни разу не встречал заказчика, способного написать вменяемое тз. =)
но хоть какая то читабельная достаточно разумная бумага, от которой можно отталкиваться, конечно, обязательна. но с преобразованием "того, что клиент хочет" в "тз" должен работать менеджер проекта, программистам этого "исходника" лучше не видеть =)

 

[crocodile2u]

не совсем понял смысл опроса, но выбрал шалками несколько подходящих пунктов + иное, укажу в топике: wiki