Siempre he sido partidario de que los comentarios en código no deberían ser necesarios, a excepción de las cabeceras (explicar el uso, dependencias y demás en una clase me parece necesario); el código debe ser sencillo, acotado y los métodos, cortitos (no en el sentido de Paquirrín; en el sentido de breves, leñe). A veces no es posible, hay campos del desarrollo que son complejos, y qué cojones; a veces sabes que nadie va a leer los diagramas UML, la documentación de arquitectura... o directamente, no hay. O a veces, heredas un código ilegible y necesitas hacerte a la idea de qué cojones hace y escribes comentarios para aclararte tú mismo, antes de respirar hondo, ir a ver a tu jefe, decirle que te vas a dedicar una semana a refactorizar un código de mierda que funciona para convertirlo en un código legible que funciona, y luego largarte montado en un unicornio dorado.
Por supuesto, los comentarios proporcionan otras cosas: por ejemplo, desahogo o risas :-)... contad vuestras experiencias; estoy seguro de que superarán a la tira POR MUCHO. xD
¿quieres leer más tiras? Entra en el listado de tiras y escoge!
Puedes usar esta tira libremente,
cumpliendo tan solo esta licencia CC:
59 comments:
Siempre está esa "idea féliz" que da un punto de optimización, rendimiento o te permite minimizar impactos de futuros desarrollos reduciendo la cohesión y el acoplamiento entre los módulos que hay que comentar sí o sí.
Pero en general, teniendo una buena metodología y disponiendo de tiempo suficiente para la fase de análisis no debería ser necesario tener muchos comentarios en el código.
Pero eso de fase de análisis ¿qué es? porque como decía un antiguo jefe mío,"esa parte de documentar te la dejas para el final, empieza a tirar código PERO YA"
Falta el Util:
/*Si has llegado aqui debugando es que no has liberado de forma correcta el objeto X, utiliza la funcion MrProperRelease() */
Yo me encontré trozos del Quijote, por lo que debe haber por ahí algún programador que lee algo más que Marvel y DC, alucinante.
La verdad es que me los he llegado a encontrar casi todos, jejeje
El más común es el :
"No quites el +1, sino no funciona nada".
Muy buena y realista la tira ;)
Cegatón: empezar la casa por el tejado, eso sí que es #marcaEspaña
Husita: JUAAAAAS. eso sí que son compañeros preocupados
Mortanauta: "que no son do whiles, que son fors, señor don Quijote"
Lara ae: xD anda que no habré visto de esos
¿SE TE HA QUEDADO PILLADO BLOQMAYÚS MIENTRAS ESCRIBÍAS EL TEXTO DE LAS VIÑETAS?
No te preocupes pasa en las mejores familias, pero podrías haberlo avisado:
/**
* SE ME HA QUEDADO PILLADO BLOQMAYÚS
* DISCULPAD POR LOS GRITOS
* GRACIAS DE ANTEBRASO
*/
Related: http://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered
Uno de los mejores posts de Stack Overflow sobre comentarios de código
A mi siempre me gustó el de "Magia, no tocar." Algo parecido habia en el codigo mágico de Carmack (si el del Doom).
PD: Me refiero a este http://en.wikipedia.org/wiki/Fast_inverse_square_root
Yo me encuentro comentarios como:
//Rethink! --> chapuza rápida que busca una idea feliz, generalmente indica código ilegible.
//Bug in JVM 1.1 --> sí, el código que mantengo es así de viejo, los becarios le hablan de usted porque a los mayores hay que respetarles.
//WTF!?!? --> El código es claramente erróneo pero lleva 5 años en producción y nadie se ha quejado. Seguramente nadie usa esa funcionalidad.
\\ autogenerated, don't touch --> contando con que hace años que no usamos estas herramientas, significa que es código ilegible que nadie en su sano juicio intentará debugar
La forma mas original de decir "he soltado un peazo de codigo pero que ni yo mismo entiendo, pero que funciona, funciona bien y ademas mantiene todo el programa y no solo un modulo" es añadir al final el comentario...
//¡Oppa Gangnam Style!
Comentarios en frances y aleman en una (mastodontica e internacional) consultora española. Ouh yeah...
Jesús Leganés Combarro: y en catalán. he visto hasta comentarios en chino (ahí yo pasando a UTF-8 el texto para luego pasarlo por el traductor xD)
¡Bob mio! Debo ser el mejor programador del Mundo Mundial, porque creo que he usado todos y cada uno de los tipos de comentario que comentas... ¿No?
Comentarios en catalán, vi con mis ojitos miopes un proyecto con dos equipos de desarrollo, en un proyecto español en España y en los que unos no podían entender los comentarios de los otros y eso en consultora de renombre "HOYGA".
A mi el que más me has gustado es:
/*
Enhorabuena, has encontrado el mensaje oculto
*/
En una ocasión, refactorizando código legado, me encontré con cosas como
/*
* De verdad que lo siento. Si lees esto es que estás refactorizando esta mierda. Mándame un correo a mail@dominio.es y te invito a una cerveza. Perdón.
*/
También son míticos los
/*
HERE BE DRAGONS
*/
Trabajo para la admón pública y me tocó modificar el tema de los asuntos propios, lo que hice fue comentar la lógica y añadir el comentario:
/*a partir del anyo 2013 no se contempla la antiguedad
regalito de marianito rajoy
si lees esto para cambiarlo, es que hemos salido de la crisis*/
Un trozo de historia en los comentarios
Lo que más leo normalmente:
/************
*
* De momento lo hacemos así y cuando acabe esta fase
* lo hacemos bien.
*
*************/
La consultoría nos está enviando a la puta mierda.
Juas que bueno.
a mi lo que me suele pasar, es que primero escribo en comentarios los pasos que debe seguir la función y luego no los borro y queda algo así como :
//Validar contenido de formulario
//guardar en la base de datos
//incrementar el contador tal
//ir a tal página de visualización.
Lo mejor es cuando encuentras un "// Los comentarios se fueron" en un código (¿deliberadamente?) ofuscado (en un perl write only).
Se te ha "olvidado" hablar del comentario heredado. Supón que existe un comentario sobre una función (no entraremos en la calidad del comentario pues es irrelevante):
// Esta funcion llama al actualizador con la IP de origen
void updater(unsigned int IP)
{
// do SOME stuff :D
}
Ahora llega un programador nuevo y copiapega dicha función en su código, acto seguido cambia la función pero no toca el comentario, queda lo siguiente:
// Esta funcion llama al actualizador con la IP de origen
int bailaLaMacarena(size_t seconds, string &dancerName, const char **LPdancingfloor)
{
return bOk; // odio la notacion hungara
}
Que hijos de puta kajajajajajjajajj lo que me has hecho reir en el laburo no tiene nombre ni apellido.
El de síndrome de touret y la nave del misterio altamente usados.
Yo en C los uso para las variables globales enumero la lista de funciones que pueden cambiar su valor, tambien los usuao para las cabezeras como dices y poco más alguna aclaración para las llaves si veo que te puedes perder con ver que cierra que. No entiendo ese afán de escribir mucho en los comentarios y luego a las variables llamarlas a, b, c, d ¿? joder nombra bien las funciones las variables etc y no te hara falta comentar tanto.
El mejor comentario que me he encontrado es un
// Continuar aquí mañana
Eso en un código que llevaba 5 años en producción sin que nadie se diera cuenta de que no funcionaba.
Yo recuerdo escribir uno que era algo del pelo de
//Por alguna razón 1 evalúa a 0 aquí.
(Y lo más triste es que no estaba vacilando)
Yo he tenido casos de una función que tira bien... hasta que entra un compañero a cambiarla por razones abstractas que no alcanzo a entender.
Eso desemboca en que deshago todos los cambios y añado:
/**
* He perdido X horas buscando errores por todo el código porque no pensaba que ibas a ser tan desgraciado de cambiar algo que funciona, y menos sin avisar.
* Mañana me llevo tu riñón derecho.
* Vuelve a tocar esto y me llevo el izquierdo.
*/
En la carnica donde soy explotado, durante una epoca oscura decidieron medir la productividad de los empleados midiendo a capon el numero de lineas picadas (no de codigo, de los ficheros directamente)
Resultado: Parrafos enteros del señor de los anillos comentados en cualquier puto srcipt para justificar la cantidad de horas perdidas en scripts tan simples que hacen llorar al niño jesus...
Tuve un jefe de programacion que le molestaban los comentarios: se habia currado una tarea programada que se ejecutaba a diario para lanzar una utilidad hecha por el con lex y yacc para limpiar de comentarios todo el codigo fuente de los repositorios (ejem, carpeta compartida en el servidor)
// Código provisional (21/03/2008)
ó
// Veces que ha cambiado esta funcionalidad (incrementar
// en 1 si te ha tocado a ti esta vez) = 13.
La tira de hoy ha despertado las fantasías de la comunicad de programadores. No entiendo la mitad de las cosas :/
El comentario nº 14 de Cegatón, muy divertido. ¿Ninguno decía "independencia para Catalunya"?
Cuando hice mi PFC tuve que crear programas para procesar los datos que me daba un programa de cálculo. Los comentarios iniciales antes del código-cutre-no-optimizado
(y lleno de comentarios obvios) ocupaban más espacio que el programa en si mismo. Contenían la descripción del programa y una descripción detallada de las variables de entrada y de salida. Muchos programas eran básicamente una función que llamaba a otras funciones que a su vez llamaban a más funciones. Un caos seguir el rastro de eso. Además que, si falta una, no funcionaba.
Si el PFC ocupó unas 200 páginas, algo más de la mitad eran los programas. Menos mal que estaba escrito en MATLAB y no había que declarar variables. Eso lo hubiera alargado todavía más.
P.D. Ahora creo que debería haber aprendido VB y haber programado con el EXCEL. Aunque los informáticos se cachondeen de VB, EXCEL es útil mientras que MATLAB y otros programas como MATHCAD o STATGRAPHICS son pijerías académicas.
P.D.2. Yo tuve una asignatura de programación en FORTRAN 77 donde se veía muy poca programación. Ahora que lo pienso, nunca se nos ocurrió lo siguiente. Si el profesor te manda hacer algo, es indudablemente algo sencillo que alguien (probablemente mucha gente) ha hecho en el pasado. Por ejemplo, ordenar de menor a mayor. Por lo tanto, no era necesario pensar mucho, sólo buscar un libro de algoritmos o en Google algún diagrama y estudiarlo.
Yo el mejor que me encontré fue
/* Tenemos un Expediente X, no intentes entenderlo y mucho menos modificarlo. Funciona.
*/
// FEDEEEEEEEEEEEEEEEEEEEEEEE que aquí es onde se hace el hash!!!
Lo de los comentarios en catalán tiene su gracia, pero al menos es fácil entenderlos... yo mantengo código escritor por y para finlandeses, así que imagínate, tengo a Google translate echando humo a diario.
// alert('fuck');
Yo escribí en un programa mio la funcionalidad del código en verso, y los mensajes que lanzaban las excepciones en latín. No puedo garantizar que fuera un latín correcto, lo que si puedo garantizar es que aun nadie me ha dicho nada... :D
Yo en ocasiones pongo disculpas para los futuros herederos de mi código.
// Ya se que que esto es una chapuza de mierda pero es lo que hay,
// no sabes tú como están las cosas por aquí.
Long long time ago en otra empresa que estuve currando puse un código (era yo muy junior por entonces) con un comentario:
// TODO: Fix this!!!!!!!
Y me fui dos semanas de vacaciones.
Al volver, me rompí la cabeza, debuggee, leí el código, probé... y aquello funcionaba y no parecía estar mal.
Decidí tirar para delante.
Días antes de poner a la criatura en producción, modifique el TODO por:
"Antes de irme de vacaciones, solo Dios y yo sabíamos que había que arreglar aquí. Actualmente, solo Dios lo sabe".
El producto estuvo en producción año y pico, yo me encargaba del soporte: Jamás vimos un fallo respecto a eso, jamás se toco el código. Más tarde abandoné la empresa y por lo que se sigue en producción.
/*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless
* night cursing the moment you thought youd be clever
* enough to "optimize" the code below.
* Now close this file and go play with something else.
*/
Juro y perjuro que me encontré este
/* Descomentar si quieres que funcione*/
/* someStuff(){...} */
A mi me pasó algo parecido a lo que le ha pasado al anónimo #40: En mi caso, había un comentario (no código) que por alguna razón si se borraba el código decidía no compilar.
Jajajaja, me he divertido con esos comentarios. Sin duda que más de alguna vez se deja alguno de ellos en un código xD
Yo me encontré en un código Indio:
/* This is for comment the following code */
if (1==2) {
....
}
Nadie más dibujaba con Ascii personajes divertidos? Ya que me tuve que comer los comments en franchute, al menos dejaba un legado simpático. Poco útil, pero simpático
Para el ilustrador ¿qué tal desactivar la revisión ortográfica del Word? :-D
Es mejor el código autodocumentado del tipo...
long johnSilver = 66; // This is a magic number.
Una buena forma de entender el código rehusable.
/* Esta función lo hace todo si sabes pasar los parámetros adecuados */
void DoEverything(...) { ; }
Gran tira! Mis dos aportes:
/* Esto no hace nada*/
....
(Seguido de docenas de línea de código que efectivamente no hacía nada y que nadie se había atrevido a borrar antes)
-------------------
/* Se reserva memoria de más porque si no da un core, no sabemos por qué */
char* ptr = (char*)malloc(tamanioEstructura + 2 );
// ojo, no borrar esta linea,si borras el comentario PETA.
Sobre una función de C que en el .h tenía diferente numero de parámetros que en su implementación pero que se llamaba usando un puntero a función. Efectivamente borrando el comentario petaba, lo cual no lo entiendo.
Una vez puestos bien los argumentos todo iba perfecto, pero el que puso el comentario tuvo que quedarse descansado.
ufff, yo he visto comentarios (y tambien logs) de todo tipo, "esto es una mierda", "chapuza", "mierda", "esto es una puta mierda pero funciona", "no da tiempo a hacerlo de otra forma", "me obligan a hacerlo asi", o las iniciales del autor con la fecha y si heredas el codigo de otra empresa o pasan los años lo mas probable que esa persona ni este, aunque me paso que estaba en una empresa y me pasaron a un proyecto que teniamos que implantar una nueva aplicacion basandonos en una antigua y leyendo codigo de la antigua vi las iniciales inconfundibles de un compañero que tuve en otra empresa 3 años antes...
aparte de los comentarios que se han dejado despues de haber hecho un copy/paste para luego cambiar una funcion completamente y lo lees y lo comparas con el codigo y no tiene nada que ver
Jajajaja
Joder no se si me he reido mas con los comentarios o con la tira de hoy (ayer).
Ejemplos de codigo que han pasado por mis manos:
(Visual Fox)
** Este codigo no deberia ejecutarse, pero como tengo miedo a quitarlo le meto un IF **
IF .F.
codigo
ENDIF
Y asi de ancho se quedo el programador.... Ni comentarlo ni nada.
o el IF 1=1 para meter en un bloque (Programadores de c# intentando hacer #region en FOX?)
y su version 1=2 para que no pase por el codigo (como el IF .F.)
Mis FAMOSISIMOS: //TODO: a ver si un dia me pongo y apaño esta chapuza que funciona por la benevolencia de algun dios pagano. (en sus versiones VB C# Fox y Cobol-> aprovecho para poner curriculum questa todo mu jodido).
Sobre el codigo tbm he visto verdaderas obras maestras.. Desde el "Select Mierda" para que pete irremediablemente cuando llega a ese punto hasta comentarios en un assert dicendo eso de "abandonad toda esperanza los que atraveseis este punto" ...
En fin. Programadores.... Una raza aun por conocer.
Luego de un millón de variables booleanas, juro y rejuro que dejé este comentario:
// Just trust me, ir works.
Otra: para separa bucles enormes dentro de una función aún más enorme (separarla en métodos era impráctico porque todas las variables y todos los DataTables dependían unos de otros) he usado arte ascii del más molón sacado de acá:
http://www.network-science.de/ascii/
Literalmente poniendo: "Bucle Principal".
Me equivoqué en el anterior post, mi comentario es:
// Just trust me, it works.
También he usado recursividad, y el bucle equivalente comentado debajo, o abusado hasta el absurdo el uso del operador ternario (y el código equivalente con ifs y elses comentado debajo) más la siguiente línea:
// made just for fun :D
Se me ha ocurrido una variante del último ejemplo. Un dibujo con el rostro de la marioneta de Saw y la frase: "que empiece el juego".
Yelinna, tu mensaje en #52 no suscita mucha confianza XD
Una de cazadores de patos, ojito que se las trae!
http://igysusamigos.blogspot.de/2010/01/me-ensena-la-documentacion-por-favor.html
/**
* He visto cosas que jamás creeriais,
* naves en llamas más allá de Orion,
* amaneceres en las puertas de Tanhause,
* y todo lo que sigue funcionando en producción
* en las fechas previstas.
* Pero todo esto se perderá si lo cambias,
* como objetos de la old generation
* en el garbage collector de la máquina virtual Java...
*/
public void amazingShit() {
...
El de síndrome de tourette me lo he encontrado yo modificando para mi uso personal código _con licencia GNU_ (un script de la distro Wifiway). Decía algo así como "Eres tan inútil que tienes que copiar el trabajo de los demás".
el mejor que me he encontrado es el del codigo que se actualiza diario por un fantasma. /* Esto se modificó ayer... */
No soy programador pero juro por el sagrado pico de Tux (que nunca se le caiga y siempre se encuentre afilado) que he usado muchos de los comentarios que muestras en esta viñeta. Muy grande.
Publicar un comentario