コメントの必要性は、コードの抽象化レベルに反比例します。
たとえば、アセンブリ言語は、ほとんどの実用的な目的のために、コメントなしではわかりません。フィボナッチ数列の項を計算して出力する小さなプログラムからの抜粋を次に示します。
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 ;
コメントがあっても、理解するのは非常に複雑です。
現代の例:正規表現は多くの場合、非常に低い抽象概念です(小文字、数字0、1、2、改行など)。彼らはおそらくサンプルの形でコメントを必要としています(IIRCのボブ・マーティンはこれを認めています)。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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
言語が抽象化階層を進むにつれて、プログラマーは誘発的な抽象化(変数名、関数名、クラス名、モジュール名、インターフェース、コールバックなど)を使用して組み込みのドキュメントを提供できます。これを利用することを怠り、それについて紙にコメントを書くのは怠け者であり、メンテナーに不名誉であり、無礼です。
私はと考えていますCで数値のレシピをほとんど逐語的な翻訳C ++での数値のレシピとして始まった私が推測する、数値レシピすべての変数で、(FORTAN中)a
、aa
、b
、c
、cc
各バージョンによって維持、など。アルゴリズムは正しいかもしれませんが、言語が提供する抽象化を活用していませんでした。そして、彼らは私を追い払った。ドブス博士の記事のサンプル-高速フーリエ変換:
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;
}
}
抽象化に関する特別なケースとして、すべての言語には特定の一般的なタスク(Cでの動的リンクリストの削除)のイディオム/標準的なコードスニペットがあります。非公式には言語の一部であるため、プログラマはこれらのイディオムを学ぶ必要があります。
それで、重要なのは、避けられない低レベルの構築ブロックから構築された非慣用的なコードにはコメントが必要だということです。そして、これは起こるよりも少ないWAAAAYが必要です。