Средства документирования и сопровождения кода

[Ragazzo]

Кто что использует? У нас впринципе классика наверное: mediawiki+mantis+phpDocumentator2, хотелось бы услышать кто возможно что используют дополнительно для каких-то фич и т. п. ?
P.S. жалко нет раздела для таких тем, а то пришлось в оффтопик кидать

 

[Absinthe]

Как-то не использовал, из-за размера команды.
Обычно кроме IDE используются репозиторий, трекер заданий (Teambox мне нравится), иногда doxygen/jsdoc-toolkit, когда код идет на экспорт.
Ну и необходимую минимальную доку по установке/настройке в README.md.
Подпишусь на ответы

 

[Ragazzo]

Absinthe
Teamlab тоже прикольная вещь, когда-то в универе использовали ну я правда не сильно его использовал хаха) ну вроде ничего такая вещь, для кооперации

 

[Ragazzo]

Странно что все молчат, у всех чтоли какие-то секретные технологии?

 

[AmdY]

Да, врятли кого-то устраивает инструментарий, не видел ещё ничего приближенного к нормальному.
Мы работаем через ibm jazz, это хороший и удобный треккер, помимо фич и дефектов поддержка и перелинковка саг, эпиков, стори и чейнджей. В итоге получается всё равно каша, пол дня приходится искать где прописанны права доступа на конкретный модуль для конкретной роли. Часто забывается перелинковка, либо работаешь со стори, хотя уже есть чейндж на неё.

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

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

Вобщем, ничего действительно хорошего я для документирования я не встречал.

 

[Ragazzo]

AmdY
Ну у нас не так много пока возможно статей в вики, но впринципе раскидав по категориям очень даже норм получается. Юнит тесты редко можно пихнуть как документацию, т.к. у нас например весь код тестами не покроешь, только разве что ключевые моменты, отвечающие за логику приложения, поэтому и используем phpDocumentator2, для быстрого доступа к описанию и т п, чтобы не бегать по IDE.

 

[флоппик]

Документировать апи есть смысл для чужих людей. Своим проще автодополнением в иде пользоватся, и ктрл+клик.

 

[AmdY]

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

 

[Ragazzo]

AmdY
Это не высер, это нормальная вещь хороший class-reference же.

 

[Вурдалак]

Я тоже пришёл к выводу, что лучше unit-тестов в данном случае ничего нет.

 

[Ragazzo]

Ну кто-нибудь дайте сюда кусок юнит теста своего... что там из него можно будет понять?как это согласуется с тем что проект должен иметь нормально задокументированную часть как по внешнему API так и class-reference для любых нужд м?

 

[Вурдалак]

проект должен иметь нормально задокументированную часть как по внешнему API так и class-reference для любых нужд м?

Кому он должен? Это тебе твои менеджеры сказали?

 

[AmdY]

Ragazzo
https://github.com/AmdY/SimplePhpFramework/blob/master/test/vendor/Frm/DBTest.php

 

[Ragazzo]

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

 

[Ragazzo]

Вурдалак
ко-ко-ко

 

[Вурдалак]

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

Так ты не в состоянии прочитать чужой unit test?

Вообще не вижу проблемы: есть класс SomeDude, Ctrl + O в среде -> SomeDudeTest и весь API с примерами.

 

[weregod]

Используем сильно перепиленный мной phpDocumentor (2-го на момент возникновения потребности генерации автодокументации не было),
раньше использовали mediawiki + bugzilla, сейчас jira + confluence.jira.

> Так ты не в состоянии прочитать чужой unit test?

Зависит от того, какой порог вхождения в документацию ставится.

 

[Ragazzo]

> Так ты не в состоянии прочитать чужой unit test?

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