coding style - tecnico - ¿Cuál es el comentario menos útil que hayas visto?
ejemplo de curriculum vitae de recursos humanos (30)
Todos sabemos que comentar nuestro código es una parte importante del estilo de codificación para hacer que nuestro código sea comprensible para la siguiente persona que aparezca, o incluso para nosotros en 6 meses más o menos.
Sin embargo, a veces un comentario simplemente no corta la mostaza. No estoy hablando de bromas obvias o frustraton expresado, estoy hablando de comentarios que parecen estar intentando explicar, pero hacerlo tan mal que bien podrían no estar allí. Los comentarios que son demasiado cortos , demasiado crípticos o simplemente son incorrectos .
Como un cuento prudente, ¿podrías compartir algo que has visto que realmente fue tan malo , y si no es obvio, mostrar el código al que se refería y señalar lo que está mal con él? ¿Qué debería haber ido allí?
Ver también:
Aplicación de 100k LOC que fue portada de vb6 a vb.net. Parece que un desarrollador anterior había puesto un encabezado de comentario en un método y luego copió y pegó el comentario exacto en cada método que escribió a partir de ese momento. Cientos de métodos y cada uno comentó incorrectamente ...
Cuando lo vi por primera vez, me reí ... 6 meses después el chiste se está agotando.
Cada comentario que simplemente repite lo que dice el código es inútil. Los comentarios no deberían decirme qué hace el código. Si no conozco el lenguaje de programación lo suficientemente bien, para entender lo que está pasando simplemente leyendo el código, no debería leer ese código en absoluto. Comentarios como
// Increase i by one
i++;
son completamente inútiles. Veo que aumenta en uno, eso es lo que dice el código, ¡no necesito un comentario para eso! Los comentarios deben usarse para explicar por qué se hace algo (en caso de que esté lejos de ser obvio) o por qué se hace algo de esa manera y no de otra manera (para poder entender ciertas decisiones de diseño que otro programador hizo que no son muy evidentes en una vez). Otros comentarios son útiles para explicar el código engañoso, donde no es posible determinar lo que está sucediendo al echar un vistazo rápido al código (por ejemplo, hay algoritmos complicados para contar el número de bits establecidos en un número; si no lo haces) saber lo que hace este código, no tienes ninguna posibilidad de adivinar qué sucede allí).
Comentarios predeterminados insertados por IDEs.
El último proyecto en el que trabajé y que utilizaba WebSphere Application Developer tenía muchos desarrolladores y contratistas de mantenimiento que no parecían molestados por los cientos, sino miles de clases de Java que contenían este tipo de cosas:
/**
* @author SomeUserWhoShouldKnowBetter
*
* To change this generated comment edit the template variable "typecomment":
* Window>Preferences>Java>Templates.
* To enable and disable the creation of type comments go to
* Window>Preferences>Java>Code Generation.
*/
Siempre hubo una fracción de segundo entre pensar que realmente había encontrado un archivo fuente bien comentado y darse cuenta de que, sí, es otro comentario predeterminado, lo que le obligó a usar SWEAR_WORD_OF_CHOICE .
En una gran aplicación VB5
dim J
J = 0 ''magic
J = J ''more magic
for J=1 to 100
...do stuff...
La referencia es obviamente ESTA ... y sí, la aplicación sin esas dos líneas falla en tiempo de ejecución con un código de error desconocido. Aún no sabemos por qué.
Encontré un archivo una vez. Miles de líneas de código, la mayoría bastante espantosas. Variables mal nombradas, condicionales difíciles en bucles y un comentario enterrado en el medio del archivo.
/* Hmmm. A bit tricky. */
GhostDoc presenta algunas muy interesantes por sí mismo.
/// <summary>
/// Toes the foo.
/// </summary>
/// <returns></returns>
public Foo ToFoo()
Los comentarios sin relleno de javadoc son particularmente inútiles. Consumen mucho espacio en pantalla sin aportar nada útil. Y la peor parte es que cuando aparece uno de esos comentarios, cientos de otros seguramente están detrás.
/**
* Method declaration
*
*
* @param table
* @param row
*
* @throws SQLException
*/
void addTransactionDelete(Table table, Object row[]) throws SQLException {
Me he encontrado escribiendo esta pequeña joya antes:
//@TODO: Rewrite this, it sucks. Seriously.
Por lo general, es una buena señal de que he llegado al final de mi sesión de codificación durante la noche.
Mi comentario favorito de todos los tiempos.
/* our second do loop */
do {
Quien lo haya escrito, ya sabes quién eres.
No lo creo Llegué a esta pregunta después de que tenía 22 respuestas, y nadie señaló el tipo de comentario menos útil posible:
comentarios que son incorrectos
Ya es suficientemente malo que las personas escriban comentarios superfluos que entorpecen la comprensión del código, pero cuando alguien escribe un comentario detallado que explica cómo funciona algo, y en primer lugar está equivocado, o es incorrecto después de cambiar el código sin cambiar el comentario ( escenario mucho más probable), ese es definitivamente el peor tipo de comentario.
Solo los comentarios típicos de Comp Sci 101:
$i = 0; //set i to 0
$i++; //use sneaky trick to add 1 to i!
if ($i==$j) { // I made sure to use == rather than = here to avoid a bug
Esa clase de cosas.
// Don''t know why we have to do this
Thread.Sleep(1000); // this will fix .NET''s crappy threading implementation
El peor comentario es uno que da una explicación incorrecta de lo que hace el código. Eso es peor que ningún comentario en absoluto.
He visto este tipo de cosas en el código con demasiados comentarios (que no deberían estar allí porque el código es lo suficientemente claro por sí mismo), y sucede principalmente cuando el código se actualiza (refactorizado, modificado, etc.) pero los comentarios no se actualizan junto con esto.
Una buena regla general es: solo escribir comentarios para explicar por qué el código está haciendo algo, no lo que hace.
Algo como esto:
// This method takes two integer values and adds them together via the built-in
// .NET functionality. It would be possible to code the arithmetic function
// by hand, but since .NET provides it, that would be a waste of time
private int Add(int i, int j) // i is the first value, j is the second value
{
// add the numbers together using the .NET "+" operator
int z = i + j;
// return the value to the calling function
// return z;
// this code was updated to simplify the return statement, eliminating the need
// for a separate variable.
// this statement performs the add functionality using the + operator on the two
// parameter values, and then returns the result to the calling function
return i + j;
}
Y así.
Definitivamente tendrían que haber comentarios que reemplacen el manejo de errores.
if(some_condition){
do_stuff();
}
else{
//An error occurred!
}
Tomado de una de mis publicaciones en el blog :
En el proceso de limpiar parte del código fuente de uno de los proyectos que administro, me encontré con los siguientes comentarios:
/*
MAB 08-05-2004: Who wrote this routine? When did they do it? Who should
I call if I have questions about it? It''s worth it to have a good header
here. It should helps to set context, it should identify the author
(hero or culprit!), including contact information, so that anyone who has
questions can call or email. It''s useful to have the date noted, and a
brief statement of intention. On the other hand, this isn''t meant to be
busy work; it''s meant to make maintenance easier--so don''t go overboard.
One other good reason to put your name on it: take credit! This is your
craft
*/
y luego un poco más abajo:
#include "xxxMsg.h" // xxx messages
/*
MAB 08-05-2004: With respect to the comment above, I gathered that
from the filename. I think I need either more or less here. For one
thing, xxxMsg.h is automatically generated from the .mc file. That might
be interesting information. Another thing is that xxxMsg.h should NOT be
added to source control, because it''s auto-generated. Alternatively,
don''t bother with a comment at all.
*/
y luego una vez más:
/*
MAB 08-05-2004: Defining a keyword?? This seems problemmatic [sic],
in principle if not in practice. Is this a common idiom?
*/
un proyecto de motor de base de datos muy grande en C hace muchos años: miles de líneas de código con nombres de variable cortos y mal escritos, y sin comentarios ... hasta que en las condiciones anidadas de varios miles de líneas en el módulo apareció el siguiente comentario :
//if you get here then you really f**ked
para ese momento, ¡creo que ya lo sabíamos!
try
{
...some code...
}
catch
{
// Just don''t crash, it wasn''t that important anyway.
}
*suspiro
// remember to comment code
wtf? :RE
// secret sauce
Este es un ejemplo absolutamente real de un disparador de base de datos:
/******************************************************************************
NAME: (repeat the trigger name)
PURPOSE: To perform work as each row is inserted or updated.
REVISIONS:
Ver Date Author Description
--------- ---------- --------------- ------------------------------------
1.0 27.6.2000 1. Created this trigger.
PARAMETERS:
INPUT:
OUTPUT:
RETURNED VALUE:
CALLED BY:
CALLS:
EXAMPLE USE:
ASSUMPTIONS:
LIMITATIONS:
ALGORITHM:
NOTES:
******************************************************************************/
/** function header comments required to pass checkstyle */
Los dos comentarios más inútiles que he visto ...
try
{
...
}
catch
{
// TODO: something catchy
}
Publiqué este en Daily WTF también, así que lo recortaré solo con el comentario ...
// TODO: The following if block should be reduced to one return statememt:
// return Regex.IsMatch(strTest, NAME_CHARS);
if (!Regex.IsMatch(strTest, NAME_CHARS))
return false;
else
return true;
Uno que nunca he encontrado muy útil:
<!--- Lasciate ogne speranza, voi ch''intrate --->
Vi este comentario ayer en una aplicación C #:
//TODO: Remove this comment.
//'' OOOO oooo that smell!! Can''t you smell that smell!??!??!!!!11!??/!!!!!1!!!!!!1
If Not Me.CurrentMenuItem.Parent Is Nothing Then
For Each childMenuItem As MenuItem In aMenuItem.Children
do something
Next
If Not Me.CurrentMenuItem.Parent.Parent Is Nothing Then
//''item is at least a grand child
For Each childMenuItem As MenuItem In aMenuItem.Children
For Each grandchildMenuItem As MenuItem In childMenuItem.Children
do something
Next
Next
If Not Me.CurrentMenuItem.Parent.Parent.Parent Is Nothing Then
//''item is at least a grand grand child
For Each childMenuItem As MenuItem In aMenuItem.Children
For Each grandchildMenuItem As MenuItem In childMenuItem.Children
For Each grandgrandchildMenuItem As MenuItem In grandchildMenuItem.Children
do something
Next
Next
Next
End If
End If
End If
AHHHRRRGGHHH Acabo de encontrar esto en algún código antiguo, apuesto a que el tipo pensó que era bastante gracioso
private
//PRIVATE means PRIVATE so no comments for you
function LoadIt(IntID: Integer): Integer;
Acabo de encontrar este, escrito en la línea antes de una línea de código comentada:
//This causes a crash for some reason. I know the real reason but it doesn''t fit on this line.
Una vez trabajé en un proyecto con un extraño compilador de C. Dio un error en una pieza válida de código a menos que se insertara un comentario entre dos declaraciones. Así que cambié el comentario a:
// Do not remove this comment else compilation will fail.
Y funcionó muy bien.