La necesidad de comentarios es inversamente proporcional al nivel de abstracción del código.
Por ejemplo, el lenguaje ensamblador es, para la mayoría de los propósitos prácticos, ininteligible sin comentarios. Aquí hay un extracto de un pequeño programa que calcula e imprime los términos de la serie 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 asimilarlo.
Ejemplo moderno: las expresiones regulares a menudo son construcciones de abstracción muy bajas (letras minúsculas, número 0, 1, 2, nuevas líneas, etc.). Probablemente necesiten comentarios en forma de muestras (Bob Martin, IIRC, lo reconoce). Aquí hay una expresión regular que (creo) debería coincidir con las URL 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 lenguajes progresan en la jerarquía de abstracción, el programador puede usar abstracciones evocativas (nombre de variable, nombres de función, nombres de clase, nombres de módulos, interfaces, devoluciones de llamada, etc.) para proporcionar documentación incorporada. Negarse a aprovechar esto, y usar comentarios para ocultarlo es vago, un mal servicio y una falta de respeto por parte del mantenedor.
Estoy pensando en Numerical Recipes en C traducido textualmente en su mayoría a Numerical Recipes en C ++ , lo que deduzco que comenzó como Numerical Recipes (en FORTAN), con todas las variables a, aa, b, c, cc, etc mantenido a través de cada versión. Los algoritmos pueden haber sido correctos, pero no aprovecharon las abstracciones que proporcionaban los idiomas. Y me joden. Muestra 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 / fragmentos de código canónico para ciertas tareas comunes (eliminar una lista dinámica vinculada en C), e independientemente de cómo se vean, no deben documentarse. Los programadores deben aprender estos modismos, ya que no son parte oficial del lenguaje.
Así que la conclusión: el código no idiomático construido a partir de bloques de construcción de bajo nivel que no se puede evitar necesita comentarios. Y esto es necesario WAAAAY menos de lo que sucede.