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

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

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

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

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

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

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

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

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

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

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

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

А пример такого описания показать можешь?

вот например https://github.com/daddyz/phonelib

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

Ткни пальцем, где там картинки?

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

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

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

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

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

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

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

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

Получается, если я не знаю Джаву, но знаю С++, то я не смогу понять о чём код. А если будет картинка - смогу.

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

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

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

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

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

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

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

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

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

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

Спасибо. Я тут совсем недавно, не освоился ещё.

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

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

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

Спасибо.

Знал бы ты, кого благодаришь, лул.

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

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

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

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

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

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

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

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

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

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

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