Il valore della documentazione del codice

La documentazione del codice è la raccolta di immagini e descrizioni scritte di facile comprensione che spiegano cosa fa una base di codice e come può essere utilizzata.

Può essere semplici commenti esplicativi sopra funzioni e blocchi, o un manuale per sviluppatori a tutti gli effetti, completo di stile prescrittivo dos-and-don’ts, panoramiche di ogni parte dell’applicazione e approcci ai tipi più comuni di attività di codifica.

Spesso è meglio trovare un mezzo felice tra questi due estremi quando si prende la decisione consapevole di commentare il codice e delineare le aree più nodose di una base di codice in un linguaggio semplice.

Perché documentare il codice?

Perché andare al problema a scrivere sul tuo codice, invece di scrivere semplicemente codice? Non sarebbe comunque più produttivo?

Punti di salvataggio mentale

La documentazione è come un punto di salvataggio mentale per quei momenti in cui finalmente ottieni quello che sta succedendo alla fine della giornata e non vuoi perdere slancio. Il codice ben documentato farà in modo che quando hai bisogno di tuffarti di nuovo domani mattina (o tra diversi mesi), non dovrai prendere tutto il tempo per aggiornarti.

Il codice documentato viene riutilizzato

La differenza tra una libreria utilizzata e una libreria inutilizzata spesso si riduce alla sua documentazione.

Chi vuole utilizzare una libreria open source non documentata o contribuire a un progetto non documentato? Quasi nessuno.

Nella maggior parte dei casi, si preferisce utilizzare una libreria meno potente con documenti. Perché? Perché la documentazione trasmette altri punti di informazioni su una base di codice. Gli sviluppatori ritengono che il progetto valga il tempo e l’energia per scriverlo in un linguaggio semplice, in modo che chiunque possa essere interessato possa iniziare rapidamente e imparare come funziona e perché sono state prese decisioni chiave.

Trovare un progetto nuovo, interessante e ben documentato nella tua lingua preferita può essere molto eccitante e divertente. Diamo un’occhiata all’alternativa estrema: essere tenuti a utilizzare una libreria di codice non documentata e potenzialmente contribuire a una base di codice apparentemente bizantina… sembra piuttosto doloroso, giusto?

Quindi perché non hai documentato il tuo codice?

Documentare il codice fa parte della scrittura di un buon codice

Una pietra angolare del buon codice è la manutenibilità, ottenuta attraverso una documentazione comprensibile e leggibile.

Esistono diversi modi per documentare il codice:

• la scelta di nomi di variabili e funzioni
• lasciando brevi commenti all’interno del codice per aiutare a fornire un contesto per i futuri lettori
• aggiunta illustrativo immagini in sequenza e diagrammi entità-relazione
• fornire API docs, la descrizione di ogni classe, il metodo, l’argomento e il valore di ritorno di
• l’utilizzo di un linguaggio tipizzato staticamente, come Dattiloscritto (tipi di documentazione)

Confrontare due esempi

diciamo che stai ricevendo alcuni dati da un API di back-end e “ingressing” it – conversione in un utile più di forma per un interfaccia utente front-end. Ecco la prima delle due possibili soluzioni.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

Il codice di cui sopra ha il potenziale per essere doloroso. Puoi vedere dal nome che questa è una sorta di convertitore che prende w come parametro.

Sembra che restituisca un’intestazione, forse dettagli e qualcosa chiamato revs. Da dove vengono i giri, comunque? Naturalmente, non ci sono dettagli sui nomi delle variabili in entrata note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… o c’è? rr è l’abbreviazione di returned rev? Chi può dirlo.

Diamo un’occhiata al secondo esempio.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

Wow, che differenza! Questa funzione è in un file util, quindi il file principale è già meno ingombrante. È anche scritto in dattiloscritto invece del semplice JavaScript, quindi abbiamo il vantaggio delle definizioni di tipo per aiutarci a guidarci.

Stiamo convertendo widgetRespDTOs in widget s. Sebbene abbreviato, abbiamo piena conoscenza di cosa sia wResp. Stiamo creando un widgetHeader e un widgetDetail, è facile da vedere. Capiamo anche cosa sono oTS e cTS. Possiamo dire che WidgetRevisionsRespDTO s sono annidati all’interno di WidgetRespDTO.

Qualcuno ha gentilmente rinominato le variabili in arrivo in modo che tutti coloro che vedono questo codice sappiano cosa sono. Infine, vediamo un Widget deve essere composto dall’oggetto {widgetHeader, widgetDetail, widgetRevisions} restituito, poiché deve corrispondere al tipo di ritorno Widget specificato in alto.

Quale codice ti sentiresti meglio a usare?

Chi ne beneficia?

Il codice ben documentato avvantaggia molte persone:

Sviluppatori junior

Poiché è in un linguaggio semplice e facile da capire, la documentazione aiuta gli sviluppatori junior e i nuovi membri del team a sentirsi sicuri di saltare in una base di codice. Questo impedisce la frustrazione e l’abbandono precoce di un compito perché diventa troppo complicato troppo in fretta.

È anche utile per gli sviluppatori junior scrivere la propria documentazione in modo che possano condividere il loro codice con gli altri e in modo che possano ottenere una migliore comprensione del loro codice.

Sviluppatori senior

Prendendo il tempo di documentare ora, gli sviluppatori senior spendono meno tempo a spiegare il loro codice ad altri in futuro.

Possono anche scrivere codice più complesso. La documentazione in linguaggio semplice consente ad altri di usarla come una scatola nera, senza dover comprendere il funzionamento interno.

Squadre &progetti open source

I cambiamenti di personale possono portare un enorme rallentamento a un progetto. Il codice aggiornato e ben documentato può fungere da assicurazione contro tali rallentamenti e consentire ai restanti membri del team di fare un passo indietro, rivedere il codice da un livello elevato e decidere la migliore linea d’azione in avanti e, se necessario, a bordo di nuovi dipendenti.

You

Quando si documenta il codice, è necessario riassumerlo. Per riassumere correttamente, devi essere in grado di capirlo, tenendo le diverse parti nella tua testa allo stesso tempo. Scrivere o contribuire alla documentazione è una scorciatoia per capire davvero una base di codice, dare enormi contributi e sentirsi come una grande parte di una grande squadra.

Una buona documentazione può PROSCIUGARE la nostra esperienza di codifica

Come programmatore probabilmente hai sentito parlare del principio Don’t Repeat Yourself come chiave per scrivere codice pulito e conciso. Invece di ripetere lo stesso blocco di codice più volte, scrivi una funzione che può essere scritta una volta e impiegata in tutta l’applicazione.

Allo stesso modo, tu e il tuo team non dovreste incorrere in problemi simili e quindi reinventare la ruota ogni volta che tentate di risolverli. Ad esempio, hai mai sentito uno dei tuoi colleghi o ti sei trovato a dire:

“Agh, ho risolto qualcosa di molto simile a questo, ma non ricordo mai come lo faccio quando viene fuori… Forse dovrei scriverlo da qualche parte, eh?”

Ti ritrovi a scansionare gli stessi thread di overflow dello stack ancora e ancora.

Salva te stesso e i tuoi colleghi questo dolore seguendo lo spirito del principio SECCO e scrivendo un documento che puoi impiegare ogni volta che il problema si presenta! Ciò aiuterà te e gli altri membri del tuo team a risparmiare tempo e ad essere più efficaci nello scrivere codice più semplice, più gestibile e più efficiente.

In che modo la documentazione del codice, o la sua mancanza, ti ha influenzato?