Potrzeba komentarzy jest odwrotnie proporcjonalna do poziomu abstrakcji kodu.
Na przykład język asemblera jest w większości praktycznych niezrozumiały bez komentarzy. Oto fragment małego programu, który oblicza i drukuje terminy z serii Fibonacciego :
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 ;
Nawet z komentarzami grok może być dość skomplikowany.
Nowoczesny przykład: Regeksy to często konstrukcje o bardzo niskiej abstrakcji (małe litery, cyfry 0, 1, 2, nowe linie itp.). Prawdopodobnie potrzebują komentarzy w formie próbek (Bob Martin, IIRC, potwierdza to). Oto regex, który (myślę) powinien pasować do adresów URL HTTP (S) i 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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
W miarę postępu języków w hierarchii abstrakcji programiści mogą używać sugestywnych abstrakcji (nazwa zmiennej, nazwy funkcji, nazwy klas, nazwy modułów, interfejsy, wywołania zwrotne itp.) W celu zapewnienia wbudowanej dokumentacji. Zaniedbanie skorzystania z tego i wykorzystanie komentarzy na papierze jest leniwe, szkoda i brak szacunku dla opiekuna.
Mam na myśli Numerical Recipes in C tłumaczone głównie verbatim do Numerical Recipes in C ++ , co wnoszę rozpoczął jako Numerical Recipes (w Fortan), ze wszystkimi zmiennymi a, aa, b, c, cc, itd utrzymywany przez każdej wersji. Algorytmy mogły być poprawne, ale nie korzystały z abstrakcji podanych języków. I odpierdolili mnie. Próbka z artykułu dr Dobbs - Szybka transformata Fouriera :
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;
}
}
Jako szczególny przypadek dotyczący abstrakcji, każdy język ma idiomy / fragmenty kodu kanonicznego do niektórych typowych zadań (usuwanie dynamicznie połączonej listy w C) i bez względu na to, jak wyglądają, nie powinny być dokumentowane. Programiści powinni nauczyć się tych idiomów, ponieważ są nieoficjalnie częścią języka.
Tak więc na wynos: nieidiomatyczny kod zbudowany z bloków niskiego poziomu, których nie można uniknąć, wymaga komentarzy. A to jest konieczne WAŻSZE mniej niż to się dzieje.