Utente:LoStrangolatore/Stubs/Guida alla programmazione/Suggerimenti

Documentazione

Per ogni pezzo di codice, chiediti cosa vorrà sapere chi leggerà il codice. La documentazione e i commenti sono importantissimi, perché permettono a chi legge il codice di comprenderne lo scopo e il funzionamento.
Ricorda, la documentazione è scritta per qualcuno che non conosce quel codice. Rispondi alle seguenti domande:

qual è lo scopo che il codice cerca di ottenere?
il codice è stato scritto come workaround temporaneo (cioè come una toppa temporanea per un certo problema)?
perché la funzione o la classe è stata implementata proprio così?

Rispondere a queste domande non solo è necessario per permettere a chiunque di leggere e modificare il tuo codice (compreso tu stesso, quando fra qualche mese avrai dimenticato le risposte a queste domande), ma anche per abituarti a riflettere su questi aspetti prima di scrivere il codice (il che ti permette di progettarlo meglio).

Inoltre, in documenti separati dal codice sorgente, puoi indicare perché la struttura del software (gerarchia delle classi, design pattern, ecc.) è stata progettata nel modo in cui è stata progettata, e quali alternative sono state prese in considerazione. E' sconsigliabile scriverlo direttamente nel sorgente, perché questi aspetti riguardano il software (o un modulo del software) nel complesso, e perché la lunghezza delle spiegazioni può distrarre il lettore dal codice sorgente.

Fonti

Andy Oram, Greg Wilson, Making Software: What Really Works, and Why We Believe It, capitolo 16 ("Code Talkers")

Codice duplicato

Evita quanto più possibile di duplicare il codice. Ha numerosi svantaggi:

è lungo da scrivere e aumenta il rischio di errori di battitura o di distrazione durante la scrittura (conseguenti errori e bug nel programma)
è lungo da leggere e da capire, anche per chi l'ha scritto (dopo un tempo sufficiente, quando avrà dimenticato la logica del programma)
ci vuole più tempo per modificarlo, perché una modifica minore deve essere ripetuta in molti punti diversi; ciò aumenta anche la possibilità di introdurre errori
...

Può essere corretto in modi diversi, a seconda di come è fatto. Per esempio, se consiste nella ripetizione di righe di codice (eventualmente stringhe) che differiscono solo per indici numerici, allora si può usare un ciclo for che parametrizza la stringa con quegli indici.