Ehi sviluppatori i diagrammi non devono essere così complessi

Sviluppatori, semplificate i diagrammi.

Per metterla semplicemente: stiamo pensando troppo ai nostri diagrammi.

Creare diagrammi è una parte importante del processo di documentazione del codice. Purtroppo, viene spesso visto come un compito arduo e che richiede molto tempo. I diagrammi diventano rapidamente troppo dettagliati e granulari. I dettagli più importanti vengono persi in un mare di complessità.

Nel tentativo di ridurre l’ambiguità nei loro diagrammi UML, gli sviluppatori spesso stabiliscono simboli specifici o standard per la lettura del diagramma. Improvvisamente, il tuo diagramma diventa così pieno di simboli che richiede un’intera conoscenza per essere letto. Hai finito per codificare all’interno del diagramma. E a meno che tu non stia creando una visualizzazione di mille pagine, non esprimerà mai il livello di dettaglio del tuo codice.

Il sentimento è buono; “Voglio che il mio diagramma sia il più preciso possibile”. Ma invece di ridurre l’ambiguità, l’hai effettivamente aumentata. Parte di questo può essere attribuito alla complicazione eccessiva dell’UML stesso, ma gli sviluppatori come noi possono essere parte della soluzione.

• IA generativa per intuizioni biomediche
• I migliori post dal 14 al 20 agosto Come utilizzare ChatGPT per convertire il testo in una presentazione PowerPoint
• GPT-3 Apprendimento a pochi esempi per il modello di linguaggio?

Sovraccaricare i diagrammi con informazioni eccessive può offuscare il messaggio previsto e confondere il lettore. Dovremmo essere più consapevoli di questi svantaggi. Nella nostra ricerca di dettagli, gli sviluppatori non devono perdere di vista il nostro obiettivo principale: comunicare efficacemente un concetto.

I diagrammi dovrebbero contenere informazioni sufficienti per essere utili e allo stesso tempo essere facili da leggere. Dovrebbero aiutare le squadre a comunicare i dettagli dell’immagine generale di un sistema software complesso – o quelli più fini. E dovrebbero essere facili – e persino divertenti – da realizzare!

Con un cambio di mentalità collettivo, nuovi strumenti di diagrammazione e un’attenzione alle integrazioni utili, possiamo far sì che i diagrammi tornino ad essere efficaci strumenti per il trasferimento di informazioni tra scrittore e lettore. Ridurre la complessità del processo ci aiuterà a rendere nuovamente divertente la creazione di diagrammi – e ci preparerà per una migliore comunicazione in un futuro ambiente di lavoro basato sull’IA.

UML non ha soddisfatto le sue aspettative, ma non è completamente inutile

La complicazione eccessiva dei diagrammi può essere ricondotta al linguaggio di modellizzazione unificato (UML).

Io stesso ho scritto delle follie dell’UML. La documentazione UML 2.2 era lunga oltre 1.000 pagine, motivo per cui l’UML è diventato associato a un lavoro preliminare scomodo e spesso inutile.

Anche se non è riuscito a diventare un linguaggio esaustivo per lo sviluppo del software, l’UML lascia comunque un’eredità importante. Non dovremmo usare i diagrammi di flusso, i diagrammi di stato, i diagrammi di sequenza o i diagrammi di flusso come sostituti del nostro codice o come progetti dettagliati. Ciò richiede troppo sforzo.

Tuttavia, questi diagrammi sono estremamente efficaci come strumenti di schizzi ad alto livello. L’UML ha raggiunto il picco come strumento di schizzo per un sistema intorno al 2000. Proprio come una tendenza di moda, sta tornando di moda.

“La completezza è nemica della comprensibilità”…

Questa è una citazione di Martin Fowler, che ha contribuito a rendere popolare l’UML negli anni ’90. Forse è ora che ascoltiamo!

I diagrammi non possono – e non dovrebbero – catturare tutte le informazioni su un sistema. Spesso sono meglio utilizzati per compiti ad alto livello: visualizzare come viene utilizzato un sistema, rappresentare graficamente il flusso logico di un processo o mappare la funzionalità di un servizio. Possono aiutarci a comunicare come i sistemi interagiscono tra loro, descrivere come i sistemi funzionano internamente, identificare aree in cui i nostri modelli possono essere semplificati e così via. In pratica, ci aiutano a trasformare le scatole nere in scatole di vetro.

…Ma l’equilibrio è essenziale

I dettagli sono ancora importanti per la documentazione del codice; si tratta semplicemente di dare priorità a ciò che è più essenziale per il lettore. Un diagramma troppo scarso di dettagli diventa inutile. A volte, si tratta solo di come presentare quei dettagli.

Forse vuoi creare un diagramma su un dettaglio specifico, complicato e di basso livello all’interno del tuo codice. Le immagini e i grafici possono ancora essere estremamente utili. Ma forse è meglio creare un diagramma separato che esplori nel dettaglio quella procedura specifica. In questo modo, non sovraccarichi un diagramma con tutte le informazioni; le suddividi in modo logico che permette ai membri del tuo team di decidere quanto approfondire le diverse parti del tuo codice.

Tre chiavi per riportare i diagrammi alle basi

Una combinazione di cambiamenti nel comportamento umano e software utili può aiutarci ad aumentare la nostra collaborazione attraverso i diagrammi:

Un Cambiamento Collettivo di Mentalità su Cosa Sono Usati i Diagrammi

I diagrammi spesso falliscono quando sono eccessivamente complicati – o eccessivamente semplificati. Ma sono anche una modalità di comunicazione. Può sembrare controintuitivo rimuovere informazioni quando il tuo obiettivo è una comunicazione chiara.

Ma troppa informazione è il nemico più grande della chiarezza. Questo è ciò che dobbiamo ricordare collettivamente.

Prima di creare un diagramma, cerca di capire pienamente ciò che vuoi comunicare. Vuoi dare una panoramica generale dell’intero sistema? O vuoi approfondire una parte specifica del tuo codice? Fai un piano di gioco e definisci uno scopo per ogni rappresentazione visiva. E non preoccuparti se tutte le tue informazioni non rientrano in un unico diagramma. Puoi sempre farne un altro.

Strumenti che Favoriscono una Miglior Creazione di Diagrammi

Parte della colpa per i diagrammi inefficaci ricade sugli strumenti di creazione di diagrammi a disposizione di un programmatore. Progettare diagrammi con PowerPoint o altri strumenti “trascina e lascia” può essere difficile. Potrebbero addirittura incoraggiare un certo modo di pensare: se sto impiegando tutto questo tempo per creare un diagramma, potrei anche includere il maggior numero possibile di informazioni.

Ecco perché i programmatori devono investire in strumenti di creazione di diagrammi che li aiutino a generare diagrammi in modo rapido e facile. Creare rappresentazioni visive dovrebbe essere semplice e divertente. Quando ciò è vero, i programmatori non esiteranno a creare più diagrammi più piccoli, adattati a uno scopo specifico, invece di cercare di inserire tutto in un’unica rappresentazione visiva per poter passare oltre.

Più Integrazioni per Rendere la Vita più Facile

Se pensavi che avrei concluso l’intero post senza menzionare l’intelligenza artificiale, mi dispiace. L’integrazione di IA generativa nei nostri strumenti di creazione di diagrammi può rendere la vita molto più facile per i programmatori. Uno strumento come ChatGPT potrebbe aiutarti a ottenere un diagramma di base più velocemente. Devi solo aggiungere ulteriori dettagli e un tocco umano.

Potremmo anche beneficiare dall’integrazione degli strumenti di creazione di diagrammi nei nostri strumenti di programmazione. Se un diagramma può essere vicino al codice sorgente (anziché in un programma o una finestra completamente separata), i programmatori non si preoccuperebbero di dover comunicare così tanto all’interno del diagramma stesso. Maggiore è la connettività, più chiara diventa la funzione del diagramma.

Il Futuro: Diagrammi, Documentazione e IA

I diagrammi sono più efficaci quando hanno uno scopo chiaro per ciò che stanno comunicando. Questo è davvero importante quando guardiamo al futuro del lavoro.

L’intelligenza artificiale continuerà a gestire ruoli sempre più specializzati. Ciò lascia agli esseri umani la possibilità di concentrarsi su ciò che fanno meglio: gestire processi, migliorare prodotti e ideare nuove idee. Man mano che sempre più processi diventano automatizzati, è importante che stabiliamo una direzione chiara con i nostri colleghi umani prima di ogni progetto. Possiamo accelerare l’innovazione solo se continuiamo a comunicare.

I diagrammi ci aiutano a comunicare dettagli essenziali con i nostri colleghi, diventando una parte importante di come collaboreremo in futuro. Trovare il giusto equilibrio tra complessità e semplicità nei nostri diagrammi diventerà sempre più importante.