LINUX.ORG.RU
ФорумTalks

Заказчик требует документировать ПО.

 


2

1

Привет, комрады.

Работаю в команде разработчиков из пяти человек. Пишем ПО на заказ. Есть три-пять основных постоянных заказчиков. И вот у одного заказчика пришёл новый техлид, который стал требовать документировать ПО. Вплоть до блок-схем алгоритмов. Требует описывать архитектуру словами и картинками.

Раньше обходились просто комментариями в коде. А теперь такие требования бесят, учитывая, что на оплате это никак не сказывается.

Кто сталкивался с подобными заказчиками и как его правильно послать?

Ответ на: комментарий от TDrive

Мы такие диаграммы часто используем для описания протоколов. Когда есть два и более учстников обмена данными. На таких диаграммах мы указываем кто за кем что делает.

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

Но. Как эти диаграммы применить для описания работы программы и её частей?

tootsoon ()
Ответ на: комментарий от olegsov

Описание алгоритма текстом - хуже, чем описание картинками. Слова, особенно русские, имеют много значений. В этом плане даже английский язык более конкретный и однозначный нежели русский.

Картинки эффективнее. Так вот какими картинками заменить блок-схемы? UML?

tootsoon ()
Ответ на: комментарий от tootsoon

Но. Как эти диаграммы применить для описания работы программы и её частей?

Программу можно разделить на компоненты? Контроллеры, декораторы, база данных, очереди, сторонние сервисы, библиотеки… все это как то взаимодействует друг с другом. У вас ООП?

TDrive ★★★★★ ()
Ответ на: комментарий от tootsoon

Про взаимодействие - понятно. А как описывать работу отдного модуля? То есть, как работает контроллер, например.

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

К описанию отдельных модулей я обычно подхожу как к описанию полноценных библиотек, назначение, апи, возможности, примеры использования….

TDrive ★★★★★ ()
Ответ на: комментарий от tootsoon

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

TDrive ★★★★★ ()
Ответ на: комментарий от tootsoon

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

TDrive ★★★★★ ()
Ответ на: комментарий от TDrive

Описание алгоритма текстом - хуже, чем описание картинками. Слова, особенно русские, имеют много значений. В этом плане даже английский язык более конкретный и однозначный нежели русский.

Поэтому я хочу картинки.

tootsoon ()
Ответ на: комментарий от tootsoon

А зачем тебе описание алгоритма? Если там есть математическое основание то напиши формулы которые используются.

Что даст картинка с алгоритмом? Ее еще и обновлять придется каждый раз. А если в модуле будет баг то в любом случае придется читать код.

TDrive ★★★★★ ()
Последнее исправление: TDrive (всего исправлений: 1)
Ответ на: комментарий от tootsoon

можешь попробовать из анрил энджина взять идеи для описания алгоритмов

https://answers.unrealengine.com/storage/temp/134772-92113044ba617409020775d9aee5d408.png

но кмк это бред, это не будет понятнее чем сам код, просто альтернативный способ записи кода для тех кто не знает ЯП.

TDrive ★★★★★ ()
Ответ на: комментарий от tootsoon

у вас проект на Java а заказчик нанял тимлида который знает C++ ?)

Если это именно то что тебе нужно тогда да, нужно чертить алгоритмы как в универе.

TDrive ★★★★★ ()
Ответ на: комментарий от tootsoon

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

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

и я не против картинок где они уместны, типа описания протоколов и процессов, я о блок-схемах функций которые требовались в российских ВУЗах раньше (не знаю как сейчас)

olegsov ()
Последнее исправление: olegsov (всего исправлений: 2)

Кто сталкивался с подобными заказчиками и как его правильно послать?

Как заказчик пошлю скорее твою конторку. Если на этапе ТЗ не озаботились документацией и схемами процессов, то делайте сейчас в мыле и панике. Будет вам наука.

Раньше обходились просто комментариями в коде.

Кто твой код будет читать? Бизнес-заказчику оно зачем?

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

djambeyshik ★★★★★ ()
Ответ на: комментарий от tootsoon

Используй игнор в профиле. Так будут отсеиваться мусорные комменты и оставаться только полезные. Можешь сходу добавить туда юзера anonymouse. Анонимно приходят те, кто боится региться и хочет безнаказано писать хрень. А насчет оценки торна - так он сам с приветом=) Здесь это, знаешь, у всех)

crypt ★★★★★ ()
Ответ на: комментарий от Zhbert

Вот тут часто что-то кричат, что лучшая документация на код - это сам код.

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

crutch_master ★★★★★ ()

Требует описывать архитектуру словами и картинками.

Всё правильно требует.

Раньше обходились просто комментариями в коде.

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

А теперь такие требования бесят, учитывая, что на оплате это никак не сказывается.

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

Кто сталкивался с подобными заказчиками

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

и как его правильно послать?

Это не нужно. Если ему нужна документация, то, скорее всего, он сам думает как вас послать.

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

crutch_master ★★★★★ ()
Последнее исправление: crutch_master (всего исправлений: 3)
Закрыто добавление комментариев для недавно зарегистрированных пользователей (со score < 50)