Потребность в комментариях обратно пропорциональна уровню абстракции кода.
Например, язык ассемблера для большинства практических целей непонятен без комментариев. Вот выдержка из небольшой программы, которая вычисляет и печатает термины ряда Фибоначчи :
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\.
+\,\;\?\'\\\+&%\$#\=~_\-]+))*$
По мере развития языков в иерархии абстракций программист может использовать вызывающие абстракции (имена переменных, имена функций, имена классов, имена модулей, интерфейсы, обратные вызовы и т. Д.) Для предоставления встроенной документации. Пренебрежение этим преимуществом и использование комментариев к статье над ним - это лень, плохая услуга и неуважение к сопровождающему.
Я имею в виду Numerical Recipes в C переведен в основном дословно Numerical Recipes в C ++ , который я заключаю начал как Numerical Recipes (в 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 меньше, чем это происходит.