La necessità di commenti è inversamente proporzionale al livello di astrazione del codice.
Ad esempio, Assembly Language è, per la maggior parte dei casi pratici, incomprensibile senza commenti. Ecco un estratto da un piccolo programma che calcola e stampa i termini della serie 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 grok.
Esempio moderno: i regex sono spesso costrutti di astrazione molto bassi (lettere minuscole, numero 0, 1, 2, nuove righe, ecc.). Probabilmente hanno bisogno di commenti sotto forma di campioni (Bob Martin, IIRC, lo riconosce). Ecco una regex 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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
Man mano che le lingue avanzano nella gerarchia dell'astrazione, il programmatore è in grado di utilizzare astrazioni evocative (nome della variabile, nomi delle funzioni, nomi delle classi, nomi dei moduli, interfacce, callback, ecc.) Per fornire la documentazione integrata. Trascurare di approfittare di questo e usare i commenti per scrivere su di esso è pigro, un disservizio e mancanza di rispetto nei confronti del manutentore.
Sto pensando di Numerical Recipes in C tradotto parola per parola a Numerical Recipes in C ++ , che deduco che era iniziato come Numerical Recipes (in Fortan), con tutte le variabili a, aa, b, c, cc, ecc mantenuta attraverso ogni versione. Gli algoritmi potrebbero essere stati corretti, ma non hanno sfruttato le astrazioni fornite dalle lingue. E mi fanno fregare. Esempio da un articolo del Dr. Dobbs - Trasformata 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 di astrazione, ogni lingua ha espressioni idiomatiche / snippet di codice canonico per determinate attività comuni (eliminazione di un elenco di collegamenti dinamici in C) e, indipendentemente da come appaiono, non dovrebbero essere documentate. I programmatori dovrebbero imparare questi modi di dire, poiché fanno parte ufficiosamente della lingua.
Quindi il take away: codice non idiomatico creato da blocchi di basso livello che non possono essere evitati richiede commenti. E questo è necessario WAAAAY meno di quanto accada.