OberonCore

Сравнительно недавно (менее полугода) я стал работать в команде программистов над одним крупным веб-проектом. Исторически сложилось так, что проект практически держится в голове у разработчиков, а документации - почти ноль (не считая нескольких документов Visio). Сложно разбираться с существующим кодом и вносить в него новую функциональность. В коде чёрт ногу сломит. Знаю, что я новичок в коллективе, но мне и сейчас непросто, потому что есть много неясностей и неоднозначностей. Я могу полдня въезжать что конкретно от меня требуется сделать, копаясь в горсти исходного кода, ибо задача описывается попросту на пальцах, в двух предложениях. Из-за нечётко поставленных задач мне приходится додумывать и продумывать все возможные ситуации и, само собой, я где-то обязательно что-нибудь упускаю.
Вот такая у нас суровая действительность.

С этим надо что-то делать, но следует принимать в учёт нынешнее положение состояние. Хочется повысить квалификацию коллектива и улучшить понимание между нами. Основную часть продумывания задания составляет работа с событиями и состояниями. Но всё это на бумажке. Так что логично, что стоит пользоваться какими-то диаграммами. Помогут ли в данном случае диаграммы UML? Я с UML не имел дела до этого.

Посоветуйте каким способом лучше всего проектировщику давать задание нашему коллективу, чтобы нам было понятно что делать. Каким подходам стоит следовать, каким ПО пользоваться (желательно с открытым кодом, а то бюджет малый) для построения диаграмм. Чтобы и для Linux и для Windows.
Просьба дать советы, которыми можно воспользоваться на практике.

Попробуйте побить проект на отдельные сервисы, взаимодействующие между собой через HTTP-вызовы. И очень строго специфицировать интерфейс каждого сервиса.

Тогда проект будет структурирован как множество "HTTP-процедур" (когда потребуется, можно дойти до HTTP-объектов).

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

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

Правильное (не единственное) разбиение на куски -- то, где удается справиться с таким описанием интерфейсов. Что соответствует рассуждениям Д.Парнаса в классической статье. С первой попытки может и не выйти.

В какие-то хитромудрые UML верить особых оснований (с учетом людских мнений) нет.
Простая фиксация сигнатур с описанием параметров и структур передаваемых данных, пред- и пост-.
Главное, чтобы все это было зафиксировано в читабельном виде.
Детали формы -- третичны.

Я и так получаю лишь часть функциональности, которую мне нужно выполнить.
Проект пишется на Ruby On Rails, на котором и так есть разделение между путями, сервисами, да ещё и с MVC. Но при этом приходится работать сразу с несколькими взаимодополняющими технологиями:
Ruby (контроллер=логика программы + модель=интерфейс запросов SQL), HTML, CSS (отображение) + JavaScript (обработка поведения) + AJAX (передача данных).
Rails "хорош" тем, что скрывает от глаз всю внутреннюю часть от программиста, в результате очень трудно определить куда подевались ресурсы. Непонятно что оптимально написано, а что - нет.
HTML, CSS, JavaScript + AJAX - это реальный спагетти. Убил бы того, кто их придумал. Даже View Builder helpers не помогают.

Но соль не в этом, а в том, что я (точнее, мы) недополучаю толковое описание, по которому можно строить программу. Нет чертежа. Всё на словах. А на словах - сами знаете как бывает: тут не так понял, там упустил, там переборщил.
Реально нужны диаграммы событий и состояний переходов (flow charts). Я сегодня чуток почитал про SWITCH-технологию Шалыто. Идея мне понравилась. Хотелось бы инженерного подхода, а не как сейчас: мазок туда, мазок здесь, нет не так. Чтобы я увидел схему и чётко понял что мне нужно делать.
Типа ДРАКОНа, чтобы наглядно. Не столько работа классами, сколько ситуации и их состояние. Какое ПО посоветуете (только на англ.)?

Ценное свидетельство, спасибо.

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

Про хороший софт для этого дела вопрос интересный, лично я не верю, что есть (не считая текстового редактора), но вдруг кто-то подскажет.

Возможно, это такое "разделение", в котором больше запутывания... Если инструмент даёт слишком много возможностей.

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

Инструмент проектирования заменить нельзя. По крайней мере, не в этом проекте.

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

По моему, вам тут помогут разве что только какие-то инструменты для (полу)автоматического анализа кода (в т.ч. строящие всякие разные графы связей, типа того же doxygen'a для плюсов/жаб и прочего).

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

Вообще, у вас классическая ситуация новичка в проекте где не сложилась традиция документирования всего и вся. Проблема таких проектов не в том, что они скажем те медленно развиваются, наоборот, команда над таким проектом может работать значительно эффективней чем команды с полностью документируемыми проектами, проблема в том, что входной порог в такой проект очень высок. Т.е. это уже не порог, а стена по сути. Особенно если проект всё ещё активно меняется. Посему с ним можно что-то (эффективно) делать лишь до тех пока есть старая команда. Если основатели уходят, то даже добиться вменяемого багфиксинга очень сложно.

Реально поможет IBM Rapsody. Которая позволит определить как всю задачу, так и отдельно взятый кусочек.

Оно языко и задаче независимо? Ибо я в серебряную пулю ну ни разу не верю.

Вопрос, несомненно, актуальный.

Тут, конечно, еще вопрос, что есть в зоне досягаемости.
Вот у меня Rhapsody нет и не предвидится, и эту штуку даже рассматривать как кандидата трудно.
Но есть InfoSelect. Который другим рассматривать как кандидата трудно.
Но у себя я бы его попробовал.
Известно, что сами разработчики IS используют его в разработке направо и налево, для кодирования в том числе.

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

По сети общение участников организовывается.

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

*нервно теребя салфетку
Это не та ли IBM Telelogic (Rational) Rhapsody, которая стоит ок. 300 тыщ рублей?

Да. Это та IBM Telelogic (Rational) Rhapsody, которая стоит от 0 до 800 тыщ рублей в зависимости от требуемого функционала.

Сама базовая программа - бесплатна, модули по Data Mining, Intellegense, Reverse Engineering, Code Generation и прочие плюшки - платные. Какие хотите - такие и покупаете.

Достоинства базы - позволяет чётко прописать кто что делает, кто за что отвечает. Сама высчитывает кто от кого зависит. Можно поделить на объекты и описать их взаимодействие. Если куплен модуль генерации кода, то она с генерирует по описанным объектами болванку на C++ или Java (смотря что куплено). Если куплен модуль реверсной инженерии, то сама разберёт ваши исходники и построит диаграммы зависимостей, классов, интерфейсов и связей с указанием ошибок, если таковые имеются. Если куплен интеллигенс, то проанализирует вашу программу на предмет отказов (статическое тестирование). Ну и много других если, в зависимости от набора модулей. Но для того чтобы упорядочить работу должно хватить базового набора.

Не сгенерирует, не разберет, не построит и не проанализирует. Просто потому, что не умеет оно ruby и, скорее всего, не умеет js с ajax'ом.

Что остается? Остаётся система тикетов и планировщик. А для этого есть куча удобных свободных инструментов (тот же trac например, или багзила). Не вижу ни одной причины чтобы завязываться на проприентарное платформозависимое решение.

Немного по теме: http://lib.custis.ru/%D0%97%D0%BE%D0%BB ... 0%BA%D0%B8