Kebutuhan akan komentar berbanding terbalik dengan tingkat abstraksi kode.
Misalnya, Bahasa Assembly, untuk tujuan praktis, tidak dapat dipahami tanpa komentar. Berikut adalah kutipan dari program kecil yang menghitung dan mencetak ketentuan dari seri 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 ;
Bahkan dengan komentar, itu bisa sangat rumit untuk grok.
Contoh Modern: Regex seringkali merupakan konstruksi abstraksi yang sangat rendah (huruf kecil, angka 0, 1, 2, baris baru, dll). Mereka mungkin perlu komentar dalam bentuk sampel (Bob Martin, IIRC, tidak mengakui ini). Berikut adalah regex yang (menurut saya) harus cocok dengan HTTP (S) dan URL 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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
Saat bahasa berkembang hierarki abstraksi, programmer dapat menggunakan abstraksi menggugah (nama variabel, nama fungsi, nama kelas, nama modul, antarmuka, panggilan balik, dll) untuk menyediakan dokumentasi bawaan. Untuk mengabaikan mengambil keuntungan dari ini, dan menggunakan komentar untuk menulis di atasnya itu malas, merugikan dan tidak sopan dari pengelola.
Saya sedang berpikir untuk Numerical Recipes di C diterjemahkan sebagian besar verbatim untuk Numerical Recipes dalam C ++ , yang saya simpulkan dimulai sebagai Numerical Recipes (di FORTRAN), dengan semua variabel a, aa, b, c, cc, dll dipertahankan melalui setiap versi. Algoritme mungkin benar, tetapi mereka tidak memanfaatkan abstraksi bahasa yang disediakan. Dan mereka membuatku kesal. Contoh dari artikel 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;
}
}
Sebagai kasus khusus tentang abstraksi, setiap bahasa memiliki idiom / cuplikan kode kanonik untuk tugas-tugas umum tertentu (menghapus daftar yang terkait dinamis dalam C), dan terlepas dari bagaimana tampilannya, mereka tidak boleh didokumentasikan. Pemrogram harus mempelajari idiom-idiom ini, karena mereka adalah bagian tidak resmi dari bahasa tersebut.
Jadi kesimpulannya: Kode non-idiomatik yang dibangun dari blok bangunan tingkat rendah yang tidak dapat dihindari membutuhkan komentar. Dan ini perlu WAAAAY kurang dari itu terjadi.