Разработчики, диаграммы не обязательно должны быть такими сложными

Разработчики, диаграммы могут быть простыми

Давайте поставим все просто: мы слишком много думаем над нашими диаграммами.

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

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

Идея хорошая: “Я хочу, чтобы моя диаграмма была как можно более точной”. Но вместо устранения неоднозначности вы ее на самом деле усилили. Часть этого можно списать на чрезмерное усложнение самого UML – но мы, разработчики, можем стать частью решения.

• Достижение превосходства в производстве с помощью моделей распознавания изображений для обнаружения дефектов поверхности
• Создание 3D-видео из RGB-видео
• Сравнение и объяснение моделей диффузии в HuggingFace Diffusers

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

Диаграммы должны содержать достаточно информации, чтобы быть полезными и при этом легко читаемыми. Они должны помогать командам общаться о крупных деталях сложной программной системы – или о более мелких. И их создание должно быть простым – и даже веселым!

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

UML не оправдал своих ожиданий, но он не совсем бесполезен

Перегруженность диаграммы может быть прослежена до единого языка моделирования (UML).

Я сам писал о недостатках UML. Документация UML 2.2 была свыше 1000 страниц, поэтому UML стал ассоциироваться с неудобными и часто бессмысленными предварительными работами.

Хотя он не смог стать всеобъемлющим языком для разработки программного обеспечения, UML все же оставил важное наследие. Мы не должны использовать блок-схемы, диаграммы состояний, диаграммы последовательности или блок-схемы в качестве замены нашему коду или жестким чертежам. Это требует слишком много дополнительных усилий.

Однако эти диаграммы являются чрезвычайно эффективными инструментами для создания высокоуровневых эскизов. UML достиг пика своей популярности в качестве инструмента для создания эскизов систем вокруг 2000 года. Как модная тенденция, он снова становится актуальным.

“Полнота есть враг понятности”…

Это цитата Мартина Фаулера, который помог популяризировать UML в 1990-х годах. Может быть, настало время послушать его!

Диаграммы не могут – и не должны – содержать всю информацию о системе. Они часто лучше всего используются для высокоуровневых задач: визуализации использования системы, диаграммирования логического потока процесса или картографирования функциональности службы. Они могут помочь нам объяснить, как системы общаются друг с другом, описать, как системы функционируют внутри, определить области, в которых можно упростить наши модели и так далее. Они помогают нам превращать черные ящики в прозрачные.

…Но баланс важен

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

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

Три ключа к возвращению диаграмм к основам

Комбинация изменения человеческого поведения и полезного программного обеспечения может помочь нам увеличить наше сотрудничество с помощью диаграммирования:

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

Диаграммы часто терпят неудачу, когда они слишком сложные или слишком упрощенные. Но они также являются средством коммуникации. Кажется противоестественным удалять информацию, когда ваша цель – ясная коммуникация.

Но слишком много информации – это самый большой враг ясности. Это то, что мы должны помнить совместно.

Прежде чем создавать диаграмму, попробуйте полностью понять, что вы хотите ясно изложить. Хотите дать общий обзор всей системы? Или вы хотите углубиться в определенную часть вашего кода? Составьте план и определите цель каждой визуализации. И не беспокойтесь, если всю вашу информацию нельзя поместить в одну диаграмму. Всегда можно создать другую.

Инструменты, которые способствуют лучшей диаграммированию

Часть вины за неэффективные диаграммы лежит на инструментах для диаграммирования, доступных разработчику. Создание диаграмм с помощью PowerPoint или других инструментов “щелкни и перетащи” может быть трудным. Они даже могут поощрять определенный способ мышления: если я трачу все это время на создание диаграммы, я могу включить в нее как можно больше информации.

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

Больше интеграций для упрощения жизни

Если вы думали, что я не упомяну искусственный интеллект во всей статье – извините. Внедрение генеративного ИИ в наши инструменты для диаграммирования может сильно упростить жизнь разработчиков. Такой инструмент, как ChatGPT, может помочь вам быстрее создавать базовую диаграмму. Вам нужно только добавить больше деталей и человеческого прикосновения.

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

Будущее: диаграммы, документация и искусственный интеллект

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

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

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