La necesidad de comentarios es inversamente proporcional al nivel de abstracción del código.
Por ejemplo, el lenguaje ensamblador es, para los fines más prácticos, ininteligible sin comentarios. Aquí hay un extracto de un pequeño programa que calcula e imprime los términos de la serie de 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 ;
Incluso con comentarios, puede ser bastante complicado de asimilar.
Ejemplo moderno: las expresiones regulares son a menudo construcciones de abstracción muy bajas (letras minúsculas, números 0, 1, 2, nuevas líneas, etc.). Probablemente necesiten comentarios en forma de muestras (Bob Martin, IIRC, sí lo reconoce). Aquí hay una expresión regular que (creo) debería coincidir con las URL de HTTP (S) y 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\.
+\,\;\?\'\\+&%\$#\=~_\-]+))*$
A medida que los idiomas avanzan hacia la jerarquía de abstracción, el programador puede utilizar abstracciones evocadoras (nombre de variable, nombres de funciones, nombres de clase, nombres de módulos, interfaces, devoluciones de llamada, etc.) para proporcionar documentación integrada. Negarse a tomar ventaja de esto, y usar comentarios para escribir sobre él es perezoso, una falta de respeto y una falta de respeto al mantenedor.
Estoy pensando en que Recetas Numéricas en C se tradujeron mayormente en forma literal a Recetas Numéricas en C ++ , que inferí que comenzó como Recetas Numéricas (en FORTAN), con todas las variables a , aa , b , c , cc , etc. mantenidas a través de cada versión. Los algoritmos pueden haber sido correctos, pero no aprovecharon las abstracciones proporcionadas por los idiomas. Y me jodieron. Ejemplo de un artículo del Dr. Dobbs - Transformada rápida de Fourier :
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;
}
}
Como un caso especial sobre la abstracción, cada idioma tiene modismos de código de idioma / canónicos para ciertas tareas comunes (eliminar una lista enlazada dinámica en C), y sin importar cómo se vean, no deben documentarse. Los programadores deben aprender estos modismos, ya que no son oficialmente parte del lenguaje.
Por lo tanto, la eliminación: el código no idiomático creado a partir de bloques de construcción de bajo nivel que no pueden evitarse necesita comentarios. Y esto es necesario WAAAAY menos de lo que sucede.