Se avete trascorso un po' di tempo come sviluppatori, è probabile che abbiate dovuto seguire alcune linee guida per documentare il vostro codice o che abbiate dovuto cercare di capire cosa fa il codice di qualcun altro molto tempo dopo che se n'è andato e spesso con poca o nessuna documentazione.
Come il codice non documentato, le pipeline prive di documentazione possono essere difficili da capire per il prossimo proprietario, soprattutto se si tratta di anni dopo aver lasciato l'azienda. Mi sono imbattuto proprio in questo problema quando ho dovuto aggiornare una pipeline creata da un ex membro del team, quindi perché non rivedere i diversi modi in cui è possibile documentare le pipeline.
Utilizzate nomi chiari per le condutture
Quando si costruisce la pipeline, è facile salvarla con il nome predefinito. Quando sarà il momento di condividerla al di fuori del proprio spazio di sviluppo, dovrà avere un nome che indichi chiaramente a cosa serve quella pipeline.
Inoltre, standardizzare una convenzione di denominazione per le pipeline e mantenere questa convenzione in modo coerente tra tutte le pipeline e le risorse dell'organizzazione. Avere un modo semplice per indicare che più pipeline sono collegate senza doverle aprire tutte renderà più facile spostare la pipeline in una posizione diversa.
Rinominare gli snap
Modificare le etichette Snap per riflettere l'azione intrapresa.
Una pipeline con solo etichette predefinite sugli snap raramente dice qualcosa di più del fatto che si leggono i dati da un posto, si fa qualcosa e li si invia da un'altra parte. In particolare, è necessario indicare cosa viene filtrato, trasformato o mappato e cosa la pipeline Execute chiama a fare.
Ecco due versioni della stessa conduttura. Quale trasmette meglio il suo scopo?
Modifica dei nomi delle viste di ingresso e di uscita
Ogni volta che si combinano i dati o li si suddivide, si può dare un'indicazione di quale sia l'obiettivo di ciascun percorso cambiando i nomi delle viste. Nella sezione precedente, il Router Snap invia i dati alle viste SSO o Non-SSO, quindi se convalido la pipeline, posso facilmente vedere se l'account che sto guardando è in un'organizzazione con SSO, senza SSO o in entrambe.
Aggiungere note sulla pipeline
Il Note della pipeline consente di aggiungere note adesive personalizzate alla pipeline. Le note possono essere nascoste o visualizzate a seconda delle necessità e un'icona sopra il pulsante della funzione consente di sapere se esistono note quando si apre una pipeline.
Utilizzare la scheda Info delle proprietà della pipeline
Questo tende a essere uno dei modi meno usati per aggiungere note alla pipeline, mentre il metodo preferito è quello delle Pipeline Notes, ma l'ho trovato particolarmente utile quando abbiamo costruito il nostro catalogo di pattern. È un ottimo modo per fornire requisiti rapidi, come il riferimento alle pipeline figlio o ai file richiesti, o informazioni storiche, come il team per cui è stata creata. Anche la possibilità di collegarsi alla documentazione esterna su come utilizzare la pipeline si è rivelata molto utile.
Questi sono i vari modi in cui potete documentare le vostre pipeline. Scopritequali sono quelli che funzionano meglio per voi.
