27 lines
3.1 KiB
Markdown
27 lines
3.1 KiB
Markdown
|
# Scheda n°10: Garantisci la qualità del codice e della documentazione
|
|||
|
|
|
|||
|
|
#### È essenziale adottare il prima possibile buone tecniche di scrittura del codice. La leggibilità del codice riduce nel tempo gli sforzi di mantenimento e di correzione dei bug per te e per i tuoi (magari futuri) collaboratori.
|
|||
|
|
|
|||
|
|
## Documenta il codice e l’architettura
|
|||
|
|
|
|||
|
|
* A volte durante lo sviluppo la documentazione viene trascurata, per mancanza di tempo o di visibilità del progetto. Però, è **cruciale per la manutenibilità del progetto**: ti permette di capire il modo in cui il codice funziona nel suo insieme, e di sapere quali parti di codice verranno affette da una modifica.
|
|||
|
|
|
|||
|
|
* **Documenta l’architettura, non solo il codice**: quando scrivi la documentazione devi essere in grado di tenere in mente la visione d’insieme e aiutare altri sviluppatori a capire come tutte le diverse componenti del codice lavorano insieme. Perciò, quando documenti il tuo progetto concentrati su diagrammi e spiegazioni chiare.
|
|||
|
|
|
|||
|
|
* **Aggiorna la documentazione assieme al codice**: il miglior modo per mantenere aggiornata la documentazione è di modificarla mano a mano che modifichi il codice.
|
|||
|
|
|
|||
|
|
* Se usi uno strumento di gestione del codice sorgente, in ciascun *commit* che modifica il sorgente puoi includere anche le modifiche alla relativa documentazione (vedi in particolare la scheda ["Gestisci il codice sorgente”](#Scheda_n°4_:_Gestisci il codice sorgente)).
|
|||
|
|
|
|||
|
|
* **Nella documentazione, non scordare di trattare la parte relativa alla sicurezza**. In particolare, puoi documentare le differenti scelte di configurazione della tua applicazione, e spiegare quali regolazioni sono più sicure.
|
|||
|
|
|
|||
|
|
## Controlla la qualità del codice e della documentazione
|
|||
|
|
|
|||
|
|
* Un codice di qualità richiede **l’adozione di buone pratiche e convenzioni di scrittura**, applicate in modo consistente in tutta l’applicazione. È anche opportuno fare riferimento a [convenzioni esistenti](https://github.com/Kristories/awesome-guidelines). Ecco alcuni esempi di buone pratiche:
|
|||
|
|
* **Usare nomi di variabile e di funzione espliciti** rende più semplice capire a colpo d’occhio cosa sta succedendo.
|
|||
|
|
* **Indentare correttamente il codice** ti permette di comprendere più velocemente la struttura del codice.
|
|||
|
|
* **Evitare la ridondanza del codice** riduce la necessità di replicare una modifica in più punti. Una svista si dimentica in fretta.
|
|||
|
|
|
|||
|
|
* **Esistono strumenti che possono aiutarti a controllare la qualità del codice**. Una volta che li hai configurati correttamente, ti eviteranno di rileggere il codice per assicurarti che le convenzioni di scrittura siano state rispettate. Alcuni esempi di questi strumenti sono:
|
|||
|
|
* **Ambienti di sviluppo integrati ** ("_IDE–Integrated Development Environments_"), magari con l’aggiunta di plugin, che possono essere configurati per rispettare le regole di indentazione, le linee vuote fra diverse porzioni di codice o la posizione delle parentesi, graffe o di altro tipo.
|
|||
|
|
* **Software di misurazione della qualità del codice** possono segnalarti duplicazioni, mancate adesioni alle regole di programmazione e potenziali bug.
|