Die Notwendigkeit von Kommentaren ist umgekehrt proportional zur Abstraktionsebene des Codes.
Zum Beispiel ist Assemblersprache für die meisten praktischen Zwecke ohne Kommentare unverständlich. Hier ist ein Auszug aus einem kleinen Programm, das Terme der Fibonacci-Reihe berechnet und ausgibt :
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 ;
Selbst mit Kommentaren kann es ziemlich kompliziert sein, zu grocken.
Modernes Beispiel: Regexe sind oft sehr niedrige Abstraktionskonstrukte (Kleinbuchstaben, Nummer 0, 1, 2, neue Zeilen usw.). Sie benötigen wahrscheinlich Kommentare in Form von Mustern (Bob Martin, IIRC, erkennt dies an). Hier ist ein regulärer Ausdruck, der (meiner Meinung nach) mit HTTP- (S) und FTP-URLs übereinstimmen sollte:
^(((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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
Während die Sprachen die Abstraktionshierarchie verbessern, kann der Programmierer evokative Abstraktionen (Variablennamen, Funktionsnamen, Klassennamen, Modulnamen, Schnittstellen, Rückrufe usw.) verwenden, um eine integrierte Dokumentation bereitzustellen. Es ist faul, dies zu vernachlässigen und Kommentare zu verwenden, um darüber zu schreiben, ein schlechter Dienst für den Betreuer und respektlos gegenüber ihm.
Ich denke dabei an Numerical Recipes in C übersetzt meist wörtlich zu Numerical Recipes in C ++ , die ich schließen , begann als Numerical Recipes (in FORTAN), mit allen Variablen a, aa, b, c, cc, usw. durch jede Version beibehalten. Die Algorithmen mögen korrekt gewesen sein, aber sie haben die Abstraktionen der bereitgestellten Sprachen nicht ausgenutzt. Und sie machen mich fertig. Auszug aus einem Artikel von Dr. Dobbs - Fast Fourier Transform :
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;
}
}
Als Sonderfall zur Abstraktion verfügt jede Sprache über Redewendungen / kanonische Codefragmente für bestimmte allgemeine Aufgaben (Löschen einer dynamischen verknüpften Liste in C). Unabhängig davon, wie sie aussehen, sollten sie nicht dokumentiert werden. Programmierer sollten diese Redewendungen lernen, da sie inoffiziell Teil der Sprache sind.
Also das Mitnehmen: Nicht-idiomatischer Code, der aus einfachen Bausteinen besteht, die nicht vermieden werden können, benötigt Kommentare. Und das ist WAAAAY weniger notwendig, als es passiert.