ความต้องการความคิดเห็นเป็นสัดส่วนผกผันกับระดับนามธรรมของรหัส
ตัวอย่างเช่นแอสเซมบลีภาษาคือเพื่อจุดประสงค์ในทางปฏิบัติส่วนใหญ่ไม่สามารถเข้าใจได้โดยไม่มีความคิดเห็น นี่คือข้อความที่ตัดตอนมาจากโปรแกรมขนาดเล็กที่คำนวณและพิมพ์เงื่อนไขของชุดฟีโบนักชี :
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 ;
แม้ว่าจะมีความคิดเห็นก็ตามมันอาจซับซ้อนมาก
ตัวอย่างที่ทันสมัย: Regexes มักจะมีโครงสร้างนามธรรมที่ต่ำมาก (ตัวอักษรตัวพิมพ์เล็กหมายเลข 0, 1, 2, บรรทัดใหม่ ฯลฯ ) พวกเขาอาจต้องการความคิดเห็นในรูปแบบตัวอย่าง (Bob Martin, IIRC รับทราบสิ่งนี้) นี่คือ regex ที่ (ฉันคิดว่า) ควรตรงกับ HTTP (S) และ FTP URL:
^(((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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
ในขณะที่ภาษาพัฒนาลำดับชั้นของสิ่งที่เป็นนามธรรมขึ้นโปรแกรมเมอร์สามารถใช้ abstractions นำมาซึ่ง (ชื่อตัวแปรชื่อฟังก์ชันชื่อคลาสชื่อโมดูลอินเทอร์เฟซการเรียกกลับ ฯลฯ ) เพื่อจัดทำเอกสารในตัว การละเลยที่จะใช้ประโยชน์จากสิ่งนี้และใช้ความเห็นในกระดาษมากกว่าความเกียจคร้านการก่อความเสียหายและการดูหมิ่นผู้ดูแล
ผมคิดว่าสูตรตัวเลขใน Cส่วนใหญ่แปลคำต่อคำเพื่อสูตรตัวเลขใน C ++ซึ่งผมอนุมานเริ่มเป็นสูตรตัวเลข (ใน FORTAN) กับตัวแปรทั้งหมดa, aa, b, c, ccฯลฯ คงผ่านแต่ละรุ่น อัลกอริทึมอาจถูกต้อง แต่พวกเขาไม่ได้ใช้ประโยชน์จาก abstractions ภาษาที่ให้ไว้ และพวกเขาปิดฉันลง ตัวอย่างจากบทความของดร. ดอบส์ - การแปลงฟูริเยร์อย่างรวดเร็ว :
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;
}
}
ในกรณีพิเศษเกี่ยวกับสิ่งที่เป็นนามธรรมทุกภาษาจะมีตัวอย่างรหัสสำนวน / Canonical สำหรับงานทั่วไปบางอย่าง (การลบรายการลิงก์แบบไดนามิกใน C) และไม่ว่าพวกเขาจะดูอย่างไรพวกเขาไม่ควรจัดทำเป็นเอกสาร โปรแกรมเมอร์ควรเรียนรู้สำนวนเหล่านี้เนื่องจากเป็นส่วนหนึ่งของภาษาอย่างไม่เป็นทางการ
ดังนั้นสิ่งที่ควรทำ: รหัสที่ไม่ใช้สำนวนที่สร้างขึ้นจากการบล็อกระดับต่ำที่ไม่สามารถหลีกเลี่ยงได้ต้องการความคิดเห็น และนี่เป็นสิ่งจำเป็น WAAAAY น้อยกว่าที่มันจะเกิดขึ้น