La necessità di commenti è inversamente proporzionale al livello di astrazione del codice.
Ad esempio, il linguaggio assembly è, per la maggior parte degli scopi pratici, inintelligibile senza commenti. Ecco un estratto da un piccolo programma che calcola e stampa i termini della serie di Fibonacci :
main:
; initializes the two numbers and the counter. Note that this assumes
; that the counter and num1 and num2 areas are contiguous!
;
mov ax,'00' ; initialize to all ASCII zeroes
mov di,counter ; including the counter
mov cx,digits+cntDigits/2 ; two bytes at a time
cld ; initialize from low to high memory
rep stosw ; write the data
inc ax ; make sure ASCII zero is in al
mov [num1 + digits - 1],al ; last digit is one
mov [num2 + digits - 1],al ;
mov [counter + cntDigits - 1],al
jmp .bottom ; done with initialization, so begin
.top
; add num1 to num2
mov di,num1+digits-1
mov si,num2+digits-1
mov cx,digits ;
call AddNumbers ; num2 += num1
mov bp,num2 ;
call PrintLine ;
dec dword [term] ; decrement loop counter
jz .done ;
; add num2 to num1
mov di,num2+digits-1
mov si,num1+digits-1
mov cx,digits ;
call AddNumbers ; num1 += num2
.bottom
mov bp,num1 ;
call PrintLine ;
dec dword [term] ; decrement loop counter
jnz .top ;
.done
call CRLF ; finish off with CRLF
mov ax,4c00h ; terminate
int 21h ;
Anche con i commenti, può essere piuttosto complicato da digerire.
Esempio moderno: i regex sono spesso costrutti di astrazione molto bassi (lettere minuscole, numero 0, 1, 2, nuove linee, ecc.). Probabilmente hanno bisogno di commenti sotto forma di campioni (Bob Martin, IIRC, lo riconosce). Ecco una espressione regolare che (penso) dovrebbe corrispondere agli URL HTTP (S) e FTP:
^(((ht|f)tp(s?))\://)?(www.|[a-zA-Z].)[a-zA-Z0-9\-\.]+\.(com|edu|gov|m
+il|net|org|biz|info|name|museum|us|ca|uk)(\:[0-9]+)*(/($|[a-zA-Z0-9\.
+\,\;\?\'\\+&%\$#\=~_\-]+))*$
Mentre le lingue avanzano nella gerarchia di astrazione, il programmatore è in grado di utilizzare astrazioni evocative (nome di variabili, nomi di funzioni, nomi di classi, nomi di moduli, interfacce, callback, ecc.) per fornire documentazione integrata. Trascurare di approfittare di questo, e usare commenti su di esso è pigro, un disservizio e irrispettoso del manutentore.
Penso a Ricette numeriche in C tradotte per lo più letteralmente in Ricette numeriche in C ++ , che deduco iniziato come Ricette numeriche (in FORTAN), con tutte le variabili a , aa , b , c , cc , ecc. Mantenute tramite ogni versione. Gli algoritmi potrebbero essere stati corretti, ma non hanno sfruttato le astrazioni fornite dalle lingue. E mi hanno fregato. Esempio di articolo di Dr. Dobbs - Trasformazione di Fourier veloce :
void four1(double* data, unsigned long nn)
{
unsigned long n, mmax, m, j, istep, i;
double wtemp, wr, wpr, wpi, wi, theta;
double tempr, tempi;
// reverse-binary reindexing
n = nn<<1;
j=1;
for (i=1; i<n; i+=2) {
if (j>i) {
swap(data[j-1], data[i-1]);
swap(data[j], data[i]);
}
m = nn;
while (m>=2 && j>m) {
j -= m;
m >>= 1;
}
j += m;
};
// here begins the Danielson-Lanczos section
mmax=2;
while (n>mmax) {
istep = mmax<<1;
theta = -(2*M_PI/mmax);
wtemp = sin(0.5*theta);
wpr = -2.0*wtemp*wtemp;
wpi = sin(theta);
wr = 1.0;
wi = 0.0;
for (m=1; m < mmax; m += 2) {
for (i=m; i <= n; i += istep) {
j=i+mmax;
tempr = wr*data[j-1] - wi*data[j];
tempi = wr * data[j] + wi*data[j-1];
data[j-1] = data[i-1] - tempr;
data[j] = data[i] - tempi;
data[i-1] += tempr;
data[i] += tempi;
}
wtemp=wr;
wr += wr*wpr - wi*wpi;
wi += wi*wpr + wtemp*wpi;
}
mmax=istep;
}
}
Come caso speciale sull'astrazione, ogni lingua ha idiomi / snippet di codice canonico per alcune attività comuni (eliminazione di un elenco dinamico collegato in C), e indipendentemente da come appaiono, non dovrebbero essere documentati. I programmatori dovrebbero imparare questi idiomi, in quanto sono ufficiosamente parte della lingua.
Quindi il take away: il codice non idiomatico creato da blocchi di basso livello che non possono essere evitati richiede commenti. E questo è necessario WAAAAY meno di quanto accada.