Riferimento per lo scripting
Questa pagina di riferimento estende le procedure ottimali descritte in Strategie di scripting con maggiori dettagli su librerie di codici, etichettatura e applicazione di stili. Per illustrare i concetti riportati di seguito, verrà utilizzato Python, ma gli stessi principi si applicano a Python e C# (zero-touch) ma con una sintassi diversa.
Quali librerie utilizzare
Le librerie standard sono esterne a Dynamo e sono presenti nei linguaggi di programmazione Python e C# (zero-touch). Dynamo dispone anche di un suo gruppo di librerie che corrispondono direttamente alla gerarchia dei nodi, consentendo all'utente di creare qualsiasi elemento nel codice che potrebbe essere creato con nodi e fili. Di seguito è riportata una guida per gli elementi a cui ciascuna libreria di Dynamo consente di accedere e per quando utilizzarne una standard.
Librerie standard e librerie di Dynamo
Le librerie standard di Python e C# possono essere utilizzate per creare strutture avanzate di flussi e dati nell'ambiente Dynamo.
Le librerie di Dynamo corrispondono direttamente alla gerarchia dei nodi per la creazione della geometria e di altri oggetti di Dynamo.
Librerie di Dynamo
ProtoGeometry*
Funzionalità: arco, riquadro di delimitazione, cerchio, cono, sistema di coordinate, cuboide, curva, cilindro, spigolo, ellisse, arco di ellisse, faccia, geometria, elica, gruppo di indici, linea, mesh, curva NURBS, superficie NURBS, piano, punto, poligono, rettangolo, solido, sfera, superficie, topologia, TSpline, UV, vettore, vertice.
Modalità di importazione:
import Autodesk.DesignScript.Geometry
``
DSCoreNodes
Funzionalità: colore, intervallo di colori 2D, data e ora, intervallo di tempo, IO, formula, logica, elenco, matematica, Quadtree, stringa, filettatura.
Modalità di importazione:
import DSCore
Tassellamento
Funzionalità: superficie convessa, Delaunay, Voronoi.
Modalità di importazione:
import Tessellation
DSOffice
Funzionalità: Excel.
Modalità di importazione:
import DSOffice
*Nota Quando si utilizza ProtoGeometry tramite Python o C#, si stanno creando oggetti non gestiti, che richiedono la gestione manuale della memoria. Per ulteriori informazioni, vedere la sezione riportata di seguito: Oggetti non gestiti.
Etichettatura con attenzione
Durante lo scripting, vengono costantemente utilizzati identificatori per denotare elementi quali variabili, tipi, funzioni e altre entità. Attraverso questo sistema di notazione simbolica, mentre si creano algoritmi si può comodamente fare riferimento alle informazioni tramite etichette, solitamente composte da una sequenza di caratteri. L'assegnazione di nomi alle cose gioca un ruolo significativo nella scrittura di un codice che possa essere facilmente letto e compreso da altri e in futuro anche dal programmatore stesso. Di seguito sono riportati alcuni suggerimenti da tenere presenti durante la denominazione di elementi nello script:
È possibile utilizzare abbreviazioni, ma spiegare l'abbreviazione con un commento:
Evitare l'etichettatura ridondante:
Utilizzare la logica positiva per i nomi delle variabili anziché la logica negativa:
Preferire la "notazione inversa":
È più adatta, in termini strutturali.
Per accorciare le catene troppo lunghe e spesso ripetute, è necessario utilizzare alias:
L'aliasing può portare rapidamente a programmi molto confusi e non standard.
Utilizzare solo parole necessarie:
"Tutto dovrebbe essere reso il più semplice possibile, ma non più semplice." – Albert Einstein
Stile coerente
In generale, esistono più modi per programmare qualsiasi cosa, quindi lo "stile personale" di scripting è il risultato delle innumerevoli piccole decisioni che si è scelto di prendere (o di non prendere) lungo la strada. Detto questo, la leggibilità e la gestibilità del codice sono un risultato diretto della sua coerenza interna e della sua conformità alle convenzioni stilistiche generali. Come regola generale, anche il codice che risulta identico in due punti dovrebbe funzionare allo stesso modo. Di seguito sono riportati alcuni suggerimenti per la scrittura di un codice chiaro e coerente.
Convenzioni di denominazione: scegliere una delle convenzioni riportate di seguito per ogni tipo di entità nel codice e attenersi ad essa.
Variabili, funzioni, metodi, pacchetti, moduli:
lower_case_with_underscores
Classi ed eccezioni:
CapWords
Metodi protetti e funzioni interne:
_single_leading_underscore(self, ...)
Metodi privati:
__double_leading_underscore(self, ...)
Costanti:
ALL_CAPS_WITH_UNDERSCORES
Suggerimento: evitare variabili con una lettera (soprattutto l, O, I) tranne che in blocchi molto corti, quando il significato è chiaramente visibile dal contesto immediato.
Utilizzo di righe vuote:
Circondare le definizioni di classi e funzioni di livello superiore con due righe vuote.
Le definizioni dei metodi all'interno di una classe sono circondate da una singola riga vuota.
È possibile utilizzare (con moderazione) righe vuote aggiuntive per separare gruppi di funzioni correlate.
Evitare spazi estranei:
Immediatamente all'interno delle parentesi tonde, quadre o graffe:
Subito prima di una virgola, un punto e virgola o due punti:
Subito prima della parentesi aperta che inizia l'elenco di argomenti di una chiamata di funzione:
Subito prima della parentesi aperta che inizia un'indicizzazione o un sezionamento:
Circondare sempre questi operatori binari con uno spazio su entrambi i lati:
Controllare la lunghezza della riga:
Non superare circa i 79 caratteri.
Limitare la larghezza richiesta per la finestra dell'editor consente di mostrare diversi file aperti affiancati e funziona bene quando si utilizzano gli strumenti di verifica del codice che presentano le due versioni in colonne adiacenti.
Le righe lunghe possono essere suddivise su più righe con il ritorno a capo delle espressioni tra parentesi:
Evitare commenti ovvi e ridondanti:
A volte meno commenti creano codice più leggibile. Soprattutto se obbliga ad utilizzare nomi di simboli significativi.
L'adozione di buone abitudini di codifica riduce la dipendenza dai commenti:
Suggerimento: i commenti indicano perché, il codice indica come.
Verificare il codice open source:
I progetti open source sono realizzati grazie alle iniziative collaborative di molti sviluppatori. Questi progetti devono mantenere un elevato livello di leggibilità del codice, in modo che il team possa collaborare nel modo più efficiente possibile. È pertanto consigliabile esaminare il codice sorgente di questi progetti per osservare le attività di questi sviluppatori.
Migliorare le convenzioni:
Chiedersi se ciascuna convenzione soddisfa o meno le esigenze imminenti.
Le funzionalità/L'efficienza sono compromesse?
Standard di C# (zero-touch)
Consultare queste pagine Wiki per indicazioni sulla scrittura di C# per la funzionalità zero-touch e sul contributo a Dynamo:
Questa Wiki illustra alcuni standard di codifica generali per la documentazione e il test del codice: https://github.com/DynamoDS/Dynamo/wiki/Coding-Standards.
Questa Wiki illustra in particolare gli standard di denominazione per librerie, categorie, nomi di nodi, nomi di porte e abbreviazioni: https://github.com/DynamoDS/Dynamo/wiki/Naming-Standards.
Oggetti non gestiti:
Quando si utilizza la libreria della geometria di Dynamo (ProtoGeometry) da Python o C#, gli oggetti della geometria che si creano non verranno gestiti dalla macchina virtuale e la memoria di molti di questi oggetti dovrà essere pulita manualmente. Per eliminare oggetti nativi o non gestiti, è possibile utilizzare il metodo Dispose o la parola chiave using. Per una panoramica, vedere questa voce Wiki: https://github.com/DynamoDS/Dynamo/wiki/Zero-Touch-Plugin-Development#dispose--using-statement.
È sufficiente eliminare le risorse non gestite che non vengono restituite nel grafico o in cui non viene memorizzato un riferimento. Per il resto di questa sezione, si farà riferimento a questi oggetti come geometria intermedia. Nell'esempio di codice riportato di seguito è mostrato un esempio di questa classe di oggetto. Questa funzione di C# zero-touch singleCube restituisce un singolo cubo, ma crea 10000 cubi aggiuntivi durante l'esecuzione. Si può far finta che quest'altra geometria sia stata utilizzata come geometria di costruzione intermedia.
Questa funzione zero-touch probabilmente provocherà un arresto anomalo di Dynamo. E ciò perché sono stati creati 10000 solidi, ma ne è stato memorizzato solo uno e ne è stato restituito solo uno. Si dovrebbero invece eliminare tutti i cubi intermedi, tranne quello restituito. Non si desidera eliminare ciò che viene restituito, perché verrà propagato nel grafico e utilizzato da altri nodi.
Il codice corretto avrà un aspetto simile al seguente:
In generale, è necessario eliminare solo la geometria come Surfaces
, Curves
e Solids
. Per essere sicuri, tuttavia, è possibile eliminare tutti i tipi di geometria (Vectors
, Points
, CoordinateSystems
).
Last updated