Comentando las limitaciones del código
Escrito por Venkman hace 9 meses
bajo una licencia de Creative Commons
651 visitas. Etiquetas: codigo, programacion, buenas-practicas
Tras una lamentable experiencia personal en el proyecto al que me he incorporado, me he dado cuenta de la necesidad de un nuevo tipo de comentario. También he recordado ese consejo de Programa como si quien vaya a mantener tu código fuera un psicópata homicida que sabe dónde vives. No soy un piscópata, pero espero que alguien esté ahora mismo sintiendo mi odio remotamente xD
Mi código hace todo y más
Expongo brevemente el caso. Existe, en el proyecto, una librería propia para la validación de formularios, con validadores para un buen número de tipos de campo. Uno de ellos es el de la validación del número de NIF, algo bastante habitual. Este NIFValidator puede -en apariencia- funcionar de dos modos. En uno sólo hay un <input> para manejar número y letra. En el otro caso hay dos, uno para el número y otro para la letra. En este segundo caso, además, el comportamiento es algo distinto puesto que, lo que hace en realidad, es rellenar la letra apropiada según vamos escribiendo el número. Es una pequeña comodidad para los usuarios aunque también un error de fiabilidad que hace inútil el propósito de la letra. Dejando esto último a un lado, me tocó la tarea de utilizar este validador en un nuevo formulario. Según el documento de requisitos, yo tendría que hacerlo con un solo campo.
Y es que, aunque el código intente decir lo contrario, el validador no funciona en este modo. De hecho, una vez inspeccionado en más profundidad es evidente que el validador tiene varias partes no terminadas. No sólo no funciona con un único campo, tampoco valida correctamente CIFs, números de residentes y algún caso más. Ojo, no lo hace bien pero el código está ahí.
Hace unos días tuve otro caso parecido con una función para la generación de fechas que, sin explicar lo que soportaba y lo que no, fallaba al usar fechas UTC.
Por supuesto que la razón última del problema es que no se han hecho pruebas. El código no ha sido probado ni para los casos en los que se usa, ni para los casos que, en toda la aplicación, no se han usado aún nunca. Y buscando en toda la aplicación, resulta que siempre se ha puesto el NIF como dos campos, número y letra, por separado.
Sólo sé que sé estas cosas
La solución, todos la sabemos, es imponer el uso de un proceso de pruebas. Bien, eso está claro. Pero esta solución no siempre es posible. Tiempo, dinero o simple negativa por parte de los responsables de autorizar esas decisiones, sobre todo en el caso -como este- de una cantidad de código enorme ya existente.
Precisamente para cuando no está en nuestra mano esta solución, o incluso teniendo un proceso de pruebas, una buena práctica que puede ayudar es la de comentar en el código las limitaciones del mismo.
Este código hace esto, pero ojo, porque esta y esta partes no están probadas/no se usan en producción en ningún sitio. La ausencia de un comentario así hace que, tras esta experiencia, yo tenga que cambiar mi actitud hacia el código. Ahora mi postura neccesariamente debe ser mucho más definsiva. No puedo fiarme del código existente, lo que supone lógicamente una pérdida de productividad importante.
Propuesta
Tampoco es que haga falta dedicarle mucho esfuerzo. Basta con seguir algunas ideas básicas que marquen por ejemplo cosas como:
// No implementado // No probado // No usado en producción en casos reales
en el caso de que no lo estén. Basta poner eso delante del método, objeto o sección apropiado. Cuando después se pruebe, se quita el comentario. O mejor aún, se puede cambiar el comentario a
// Probado: OK
En resumen, no importa tanto el hecho de que las cosas funcionen como el de saber qué cosas funcionan y cuáles no.
Si puedes, intenta -por tu cuenta si hace falta- hacer pruebas del código. Pero independientemente de eso, cuando escribas código, comenta sus limitaciones para que luego, después de los años, no tengas la sensación de que alguien en algún sitio te está enviando malas vibraciones.
Artículos Relacionados
Gonzalo García (a veces Venkman) es un tipo con cierto interés por la programación, los lenguajes y el conocimiento del mundo en general. Ingeniero Industrial camuflado de programador, reparte su tiempo entre el aprendizaje y el desarrollo. Acepta ofertas de empleo. Hazle una!
11 comentarios en "Comentando las limitaciones del código"
Shirase escribió
hace 9 meses
GreenEyed escribió
hace 8 meses
Yo lo que uso es el tag //TODO: para ese tipo de comentarios, ya que es una especie de estándar de facto y algunos IDE, como por ejemplo Eclipse, son capaces de reconocerlos y marcarlos, añadiendolos incluso a las tareas pendientes del proyecto (warnings).
Trabajar con código ajeno es muy duro.
S!
Venkman escribió
hace 8 meses
Cierto!! Excelente sugerencia la del TODO:.
No me acordé porque llevo poco tiempo probando IDEA que también lo soporta pero no me acabo de hacer a sus manías (o a su pesadez).
amuino escribió
hace 8 meses
En lugar de anotar un método como "No implementado" o "No usado", es mejor no escribirlo directamente.
Sobre las pruebas, ya es más difícil. Yo prefiero crear la prueba (en Eclipse es inmediato) y dejarla como fallida (fail("Caso no probado") por ejemplo).
Como con todo, depende mucho del entorno de trabajo.
Venkman escribió
hace 8 meses
En lugar de anotar un método como "No implementado" o "No usado", es mejor no escribirlo directamente.
Mmmm... Esa es una teoría muy buena. Lamentablemente la experiencia me dice que existen múltiples situaciones en las que no se sigue esa teoría.
Pero ojo, que no se trata de algo tan simple como declarar un método pero dejarlo vacío. Eso sería trivial. El problema viene cuando parte de un método o determinada funcionalidad se deja abierta pero no terminada. Es decir, que "No implementado" no tiene por qué referirse a un método completo, sino a una funcionalidad (por ejemplo, a un modo de funcionamiento de ese método).
En cuanto a "No usado"... Sé positivamente que cualquiera puede caer en la tentación de añadir una funcionalidad que hoy no se usa pero que seguro que más adelante lo necesitamos. Ya, ya, teóricamente la solución es no caer en esa tentación. En la práctica, así es la vida.
amuino escribió
hace 8 meses
Estoy de acuerdo en que las situaciones particulares nos pueden llevar por caminos oscuros ("en la teoría, teoría y práctica son iguales... pero en la práctica son diferentes")... pero mejor que recomendar cómo documentar esos rincones es eliminar el trabajo antes de escribirlos o el riesgo (antipatrón flujo de lava) si nos los encontramos ya hechos.
Si vas a hacer un esfuerzo (añadir un comentario) que sea el más rentable. Si no, sólo estás haciendo la mitad de lo que podrías.
Es decir, un comentario es mejor que nada, pero peor que una solución.
Por hacer un simil... un cartel avisando "cuidado, puente roto" es mejor que ningún aviso... pero lo que realmente querríamos es que se hubiese arreglado el puente (o hubiesen indicado una ruta alternativa en una intersección anterior, para no tener que desandar el camino).
En la vida real las cosas se complican por muchos motivos, pero si hay que recomendar algo, recomendemos la solución y no el parche.
GreenEyed escribió
hace 8 meses
A mi me gusta programar de forma "incremental", así que normalmente no dejo código no probado o cosas a medias en productos supuestamente terminados, ya que si no "está hecho", normalmente "no está", pero realmente lo de recomendar una cosa o ser pragmático... la verdad es que es un tema complicado.
Al fin y al cabo, seguramente la gente que hace este tipo de cosas ni lee este tipo de foros ni sigue ninguna recomendación... así que... jejeje.
amuino escribió
hace 8 meses
@GreenEyed: ahí le has dao :-)
Venkman escribió
hace 8 meses
Por tomar tu simil del puente, amuino, hacer un puente cuesta seguramente unos miles de veces más que poner un cartel, tanto en tiempo como en dinero. Es posible disponer en un momento dado de un número razonable de carteles pero ni de milagro disponer de los recursos para hacer el puente.
Sin embargo, me importa más el caso de un puente que está ahí y no está roto y se ve razonablemente sólido, pero que no tiene ningún cartel diciendo "Peso máximo: 3000Kg". Si el puente está roto de forma evidente, el daño es relativamente pequeño: buscaremos otro camino. Si el puente está aparentemente en funcionamiento, lo intentaremos cruzar y caeremos al abismo. (Efecto sonoro de película de terror) (xD)
Si vas a hacer un esfuerzo, que sea, antes que el más rentable, uno que sepas que puedes hacer.
Por supuesto que me encantaría recomendar "haced las cosas bien" y desde luego lo hago. Pero en este caso la recomendación es "Haced las cosas bien, pero si no es posible hacerlas bien, por lo menos avisad de las limitaciones de lo que hacéis". Porque si nos quedamos en la primera recomendación, la cosa realmente se convierte en "Haced las cosas bien, pero si no es posible hacerlas bien, pues nada".
ajbalmon escribió
hace 6 meses
Yo, gracias a Dios (y gracias a que les mandé a tomar viento, por decirlo suavemente), dejé recientemente un proyecto, entre otras cosas, por el tema de los "puentes", los comentarios y los errores.
El caso es que llegó a mis manos un proyecto grande, interesante, importante, pero que llevaba tiempo en producción y lo que se hacía eran ampliaciones y correcciones de supuestos fallos.
Cada vez que me tocaba modificar algo que había hecho otra persona me encuentraba con comentarios mínimos y totalmente inútiles, tipo "aquí empieza el bucle" o "aquí termina el bucle", pero rara vez se explicaba para qué servía una variable, un procedimento o una función.
Rara vez había alguno que sirviera de algo.
Lo que sí me gustaba era que en los comentarios se indicaba el número de versión, pero lo peor es que varios (muchos) procedimientos habían sido modificados a lo largo de numerosas versiones, y las únicas correcciones eran parches, más parches, parches sobre parches, parches de parches sobre parches...etc, etc, etc...Sí, un caos absoluto.
Me encontré con numerosos "puentes" que daban soluciones a diversas problemáticas, pero todos esos "puentes de cuerda roída a punto de romperse" podían unirse de forma fiable y segura en un "robusto puente de hierro y acero inoxidable", lo cual hice en alguna ocasión y, a pesar de que todo funcionaba bien, hubó algún que otro mosqueo.
El problema de ese código es que, como siempre ocurre, los jefes lo quieren todo para ayer. Pero lo peor de todo fue el comentario de uno de esos jefes: "tú, termínalo para el lunes que lo entregamos al cliente, que ya lo probará él, los errores no me preocupan tanto como que el cliente tenga su proyecto en la mano, ya se corregirán". ¡¡ Ahí queda eso !!
Con ese comentario llegué a comprender por qué el código estaba tan mal hecho en todos los sentidos. Si ni siquiera los que mandan se preocupan por hacer un buen software...
« Anterior 1 2 Siguiente »
© Copyright 2008-2009 debug_mode=ON | Aviso legal | Contacto | FAQ | ¿Quiénes somos?
|
#1
Soy un maníatico de los comentarios, me gusta tener cada método bien comentado hasta los más triviales, sobre todo si veo que la solución que se me ha ocurrido no he podido dejarla fácilmente entendible para un segundo lector. Suelo explicar el cómo y/o el porqué he hecho algo, pero lo que nunca se me había ocurrido es utilizar los comentarios así.
A partir de ahora lo pondré en práctica.