Le besoin de commentaires est inversement proportionnel au niveau d'abstraction du code.
Par exemple, Assembly Language est, dans la plupart des cas, inintelligible sans commentaires. Voici un extrait d' un petit programme qui calcule et imprime les termes de la série de 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 ;
Même avec des commentaires, ça peut être assez compliqué de parler.
Exemple moderne: Les expressions rationnelles sont souvent des constructions d'abstraction très basses (lettres minuscules, chiffres 0, 1, 2, nouvelles lignes, etc.). Ils ont probablement besoin de commentaires sous forme d'échantillons (Bob Martin, IIRC, le reconnaît). Voici une regex qui (je pense) devrait correspondre aux URL HTTP (S) et 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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
À mesure que les langues progressent dans la hiérarchie des abstractions, le programmeur peut utiliser des abstractions évocatrices (nom de variable, noms de fonction, noms de classe, noms de module, interfaces, rappels, etc.) pour fournir une documentation intégrée. Négliger d'en tirer parti et utiliser des commentaires sur du papier est paresseux, nuisible et irrespectueux envers le mainteneur.
Je pense Recettes numériques en C traduit la plupart du temps verbatim Recettes numériques en C ++ , que je déduis commencé comme recettes numériques (en FORTAN), avec toutes les variables a, aa, b, c, cc, etc maintenu par chaque version. Les algorithmes étaient peut-être corrects, mais ils ne tiraient pas parti des abstractions fournies par les langages. Et ils me baisent. Échantillon d' un article du Dr. Dobbs - Transformée de Fourier rapide :
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;
}
}
En tant que cas particulier relatif à l'abstraction, chaque langue a des idiomes / extraits de code canoniques pour certaines tâches courantes (suppression d'une liste liée dynamique en C) et, quelle que soit leur apparence, ils ne doivent pas être documentés. Les programmeurs devraient apprendre ces idiomes, car ils font officieusement partie du langage.
Donc, ce qu'il faut enlever: Un code non idiomatique construit à partir de blocs de construction de bas niveau qui ne peuvent pas être évités a besoin de commentaires. Et cela est moins nécessaire que prévu.