Saltar al contenido

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript... y lo que venga ;)

17 años online

el blog de José M. Aguilar

Inicio El autor Contactar

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web
ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript...

¡Microsoft MVP!
Mostrando entradas con la etiqueta comentarios. Mostrar todas las entradas
Mostrando entradas con la etiqueta comentarios. Mostrar todas las entradas
lunes, 3 de diciembre de 2007
Hace unos días publicaba una entrada donde hablaba de los problemas que generan la inclusión y el mantenimiento de comentarios en el código fuente de nuestras aplicaciones, aunque para no extenderme mucho sólo cité brevemente algunos aspectos a tener en cuenta a la hora de afrontar estos inconvenientes.

Ahora, partiendo de estos consejos, la abundante literatura que hay sobre el tema y mi propia experiencia, he creado los 13 consejos para comentar tu código, que contribuirán a hacerlo más inteligible y por tanto a incrementar su mantenibilidad a lo largo del tiempo.

1. Comenta a varios niveles

Comenta los distintos bloques de los que se compone tu código, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como:
  • En cada clase, incluir una breve descripción, su autor y fecha de última modificación
  • Por cada método, una descripción de su objeto y funcionalidades, así como de los parámetros y resultados obtenidos
En realidad, lo importante es ceñirse a unas normas (comúnmente aceptadas si se trata de trabajo en equipo) y aplicarlas siempre. Las reglas concretas pueden ser elegidas a la conveniencia de cada cual.

Obviamente, una solución bastante aceptable e incluso aconsejable es utilizar las convenciones y herramientas (como XML en C# ó Javadoc para el mundo Java) que ayudan y facilitan esta tarea.

2. Usa párrafos comentados

Como complemento al punto anterior, es recomendable dividir un bloque de código extenso en "párrafos" que realicen una tarea simple, e introducir un comentario al principio de forma que se guíe al lector, precediéndolos, además, de una línea en blanco que ayude a separar cada uno del anterior.
  ...


// Comprobamos si todos los datos
// son correctos
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
...
}
}


// Ahora pasamos a realizar las
// transacciones
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
...

3. Tabula por igual los comentarios de líneas consecutivas

Si tenemos un bloque de líneas de código donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posición, de forma que quedarán alineados y serán más sencillos de leer, sobre todo si forman parte de la misma frase.
  const MAX_ITEMS = 10; // Número máximo de paquetes
const MASK = 0x1F; // Máscara de bits TCP
 
Ojo a las tabulaciones. Hay editores que usan el carácter ASCII (9) y otros, en cambio, lo sustituyen por un número determinado de espacios, que suelen variar según las preferencias personales del desarrollador. Lo mejor es usar espacios simples o asegurarse de que esto es lo que hace el IDE correspondiente.

4. No insultes la inteligencia del lector

Debemos evitar comentarios absurdos como:
   if (a == 5)     // Si a vale cinco, ...
counter = 0; // ... ponemos el contador a cero
...
 
Este exceso necesita mucho tiempo a la hora de su creación, lo necesitará para su mantenimiento y, además, la mayoría de las veces distraerá al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al código.

5. Sé correcto

Evita comentarios del tipo "ahora compruebo que el estúpido usuario no haya introducido un número negativo", o "este parche corrije el efecto colateral producido por la patética implementación del inepto desarrollador inicial".

El uso de este tipo de comentarios no dice nada a favor de su creador, y, además, nunca se sabe quién los va a leer en el futuro. Emarts, en "Sapos, culebras y código fuente" muestra ejemplos de comentarios de este tipo.

Otro tema relacionado y, a mi entender, igualmente importante: cuida la ortografía. El hecho de que los comentarios no se vean desde el exterior no implican que puedas descuidarlos. Una ortografía correcta mejora la calidad de la expresión escrita y, por tanto, de la comunicación, que es de lo que se trata.

6. No pierdas el tiempo

No comentes si no es necesario, no escribas nada más que lo que necesites para transmitir la idea. Nada de diseños realizados a base de caracteres ASCII, ni florituras, ni chistes, ni poesías, ni chascarrillos.

En resumen, mantén los comentarios simples y directos, pues de lo contrario harás perder tiempo a tu sucesor. Para entender el efecto negativo de una verborrea excesiva, no hay como echar un vistazo a Hyperverbosity, publicado en Worse Than Failure hace unos días.

7. Utiliza un estilo consistente

Hay quien opina que los comentarios deberían ser escritos para que los entendieran no programadores. Otros, en cambio, piensan que debe servir de ayuda para desarrolladores exclusivamente.

En cualquier caso, coincidiendo con Ryan Campbell en su post Successful Strategies for Commenting Code, lo que importa es que siempre sea de la misma forma, orientados al mismo destinatario. Personalmente, dudo mucho que alguien de un perfil alejado a la programación vaya a acercarse al código, por lo que, para mi gusto, bastaría con cubrir el segundo caso de los expuestos anteriormente.

8. Para los comentarios internos usa marcas especiales


Y sobre todo, aunque no únicamente, cuando se trabaja en un equipo de programación en el que varias personas pueden estar tocando las mismas porciones de código. El ejemplo típico es el comentario TODO (to-do, por hacer), que describe funciones pendientes de implementar:
  int calcula(int x, int y)
{
// TODO: implementar los cálculos
return 0;
}
 
En este caso los comentarios no se usan para explicar una porción de código, sino para realizar anotaciones sobre el mismo a las que hay que prestar especial atención. Eso sí, si usas esta técnica, recuerda que debes actualizarlos conforme las anotaciones dejen de tener sentido.

9. Comenta mientras programas

Ve introduciendo los comentarios conforme vas codificando. No lo dejes para el final, puesto que entonces te costará más de el doble de tiempo, si es que llegas a hacerlo. Olvida las posturas "no tengo tiempo de comentar, voy muy apurado", "el proyecto va muy retrasado"... son simplemente excusas. Si tu intención es comentar el código, no te engañes y ¡hazlo!

Hay incluso quien opina que los comentarios que describen un bloque deberían escribirse antes de codificarlo, de forma que, en primer lugar, sirvan como referencia para saber qué es lo que hay que hacer y, segundo, que una vez codificado éstos queden como comentarios para la posteridad. Un ejemplo:

public void ProcesaPedido()
{
// Comprobar que hay material
// Comprobar que el cliente es válido
// Enviar la orden a almacén
// Generar factura
}

La codificación de cada una de las tareas descritas en el lenguaje correspondiente se realizaría justo debajo del comentario, quedando éste como encabezado de párrafo (como se describe en el consejo 2).

10. Comenta como si fuera para tí mismo. De hecho, lo es.

A la hora de comentar no pienses sólo en mantenimiento posterior, ni creas que es un regalo que dejas para la posteridad del que sólo obtendrá beneficios el desarrollador que en el futuro sea designado para corregir o mantener tu código.

En palabras del genial Phil Haack,
"tan pronto como una línea de código sale de la pantalla y volvemos a ella, estamos en modo mantenimiento de la misma"

Como consecuencia, nosotros mismos seremos los primeros beneficiaros (o víctimas) de nuestro buen (o mal) hacer.

11. Actualiza los comentarios a la vez que el código

De nada sirve comentar correctamente una porción de código si en cuanto éste es modificado no se actualizan también los comentarios. Ambos deben evolucionar paralelamente, pues de lo contrario estaremos haciendo más difícil la vida del desarrollador que tenga que mantener el software, al facilitarle pistas incorrectas para comprenderlo.

Atención especial a las refactorizaciones automáticas, que suelen introducir cambios en distintos puntos del código de un proyecto, dejando los comentarios obsoletos en ese mismo instante.

12. La regla de oro del código legible

He dejado para el final uno de los principios básicos para muchos desarrolladores: deja que tu código hable por sí mismo. Aunque se sospecha que este movimiento está liderado por programadores a los que no les gusta comentar su código ;-), es totalmente cierto que una codificación limpia puede hacer innecesaria la introducción de textos explicativos adicionales.

Recordemos, por ejemplo, el código introducido en el post "Interfaces fluidos (fluent interfaces)", donde se muestra lo que esta técnica puede aportar a la claridad y autoexplicación en un desarrollo:

Console.WriteLine("Resultado: " +
new Calculator()
.Set(0)
.Add(10)
.Multiply(2)
.Substract(4)
.Get()
);
 
A la vista del ejemplo, ¿es necesario añadir algún comentario para que se entienda qué hace el código? El uso de nombres apropiados (aconsejo leer el clásico Ottinger's Rules), indentación correcta y la adopción de guías de estilo (podéis ver algunas en la wikipedia, o googleando un poco) facilitan enormemente la escritura homogénea e inteligibilidad directa del código.

El no cumplimiento de esta regla hace que a veces los comentarios puedan parecer una forma de pedir perdón al desarrollador que se encargará del mantenimiento del software.

13. Difunde estas prácticas entre tus colegas

Obviamente, aunque ya hemos comentado en el punto 10 que nosostros mismos nos beneficiamos inmediatamente de las bondades de nuestro código comentado, la generalización y racionalización de los comentarios y la creación código inteligible nos favorecerá a todos, y sobre todo en contextos de trabajo en equipo. No dudes, por tanto, en crear cultura de comentarios en tu entorno.

Publicado en: Variable Not Found.
domingo, 25 de noviembre de 2007
Si existieran los diez mandamientos del programador, seguro que uno de ellos sería "comenta tu código". Y es que está claro que la mantenibilidad de una aplicación o módulo es posible siempre que los profesionales encargados de ella sean capaces de entender perfectamente qué hace el software y cómo lo hace, y es aquí donde un código correctamente documentado puede facilitar enormemente la tarea.

Todos los lenguajes de programación facilitan la inclusión de texto libre, no estructurado, con objeto de que el programador explique a futuros mantenedores del software los principales aspectos del código fuente que está observando, el por qué de determinadas decisiones, o, en definitiva, aclarar lo que considere oportuno. Sin embargo, esta libertad y falta de normalización acarrea una serie de inconvenientes que deben ser tenidos en cuenta, y que comentó Chad Myer hace unas semanas.

En primer lugar, es importante ser conscientes de que estos textos están fuertemente ligados al código que comentan y, obviamente, al no ser comprobados por ningún sistema automático (como un compilador), es fácil que contengan errores:

// Retorna la suma de a y b
public int multiplica(int a, int b)
{
...
 
Tampoco puede asegurarse que los comentarios sean útiles; de hecho, parte de los comentarios que leemos son obviables y totalmente innecesarios, auténticos insultos a la inteligencia, del tipo:

if (a > 5) // Si a es mayor que cinco, ...
counter = 0; // ... ponemos el contador a cero
...
 
La inclusión de este tipo de comentarios no harían sino añadir "ruido" a un código perfectamente inteligible de forma directa.

Y hablando de comentarios prescindibles, es curioso ver su utilización como vía de escape y desfogue de algunos programadores, que no dudan en añadir todo tipo de artillería a sus creaciones, como las mostradas en el Contador de palabrotas del Kernel de Linux, arremetiendo contra los usuarios, colegas o todo aquél que pase por delante en el momento apropiado.

Otro hecho bastante frecuente es que los comentarios sean introducidos al crear un código pero que no sean actualizados de forma paralela a éste, lo que da lugar a textos obsoletos y sin sentido en su contexto. Y no hablo sólo de actualizaciones tiempo después de su creación, también las realizadas minutos u horas después de la programación inicial como consecuencia de optimizaciones y refactorizaciones, incluso realizadas por el mismo desarrollador.

// Si x es true, retorna a+b
// Si no, retorna a-b
public int calcula(int a, int b)
{
...
 
A pesar de todos estos problemas, normalmente generados por falta de rigor durante su creación y actualización, los comentarios son absolutamente necesarios para el futuro mantenimiento de un sistema y deben tratarse como parte fundamental en una pieza de código y prestarle la misma atención que a éste. Recordemos la famosa frase de Martin Fowler:
"Cualquier tonto puede escribir código que entienden las computadoras. Los buenos programadores escriben código que entienden las personas"


Para ello, como dice Bernhard Spuida en su magnífico documento The Fine Art of Commenting, hay que luchar contra actitudes negativas como:
  • el orgullo del programador ("no me hacen falta comentarios para entender lo que hace cualquier código", "yo escribo código que entiende cualquiera"). No te engañes, un código medianamente complejo te llevará tiempo entenderlo en cuanto hayan pasado unos meses incluso a tí mismo, así que imagina a otro desarrollador.
  • la pereza y procrastinación ("ya comentaré el código más adelante"). No te engañes, no lo harás; además, se estima que el tiempo necesario para añadir comentarios útiles a un código se duplica (como mínimo) si no se realiza en el momento de la codificación.
  • la excusa del deadline ("el proyecto va demasiado apurado como para ponerme a comentar el código"). No te engañes, los minutos de tardarás en comentar apenas afectarán a los plazos, y sí añadirán mantenibilidad al sistema.

Y es que, citando a Ryan Campbell en su post Successful Strategies for Commenting Code,
"comentar el código es como limpiar el cuarto de baño; nadie quiere hacerlo, pero el resultado es siempre una experiencia más agradable para uno mismo y sus invitados"


Publicado en: Variable Not Found.
lunes, 10 de septiembre de 2007
Hoy seguiremos jugado un poco más con las plantillas de Blogger, y estudiaremos cómo modificar la forma en que este gestor de blogs, sobre el que está montado Variable not found, muestra el mensaje al pie de los posts indicando el número de comentarios de cada entrada, que es bastante soso (al menos en las plantillas por defecto).

Por defecto Blogger nos deja configurar exclusivamente qué texto aparecerá detrás del número de comentarios, es decir, a lo más podríamos hacer que apareciera "3 comentarios, ¡comenta ya!" o mensajes así, pero nunca con lógica dependiente del número, lo cual resulta demasiado lineal y cutre para un blog de renombre como el nuestro ;-)

A lo largo de este post vamos a modificar la plantilla para hacer que se muestre un mensaje cuando no hay ningún comentario, otro distinto cuando hay sólo uno, y otro para el resto de los casos. Esto podríais después complicarlo todo lo que queráis, pero de momento con lo que vamos a ver será suficiente para que podáis empezar a jugar.

En primer lugar he de decir que, al igual que ocurría el otro día cuando tratamos el tema de modificar la forma de aparecer la lista de categorías en Blogger, lo más prudente es hacer una copia de seguridad de la plantilla, pues cualquier paso en falso puede tumbar nuestra bitácora. Por si no viste el post anterior, la forma de hacerlo era accediendo al panel de administración de la herramienta y pulsando el enlace "Descargar plantilla completa" que encontrarás en la pestaña "Plantilla", opción "Edición de HTML".

Una vez realizado el backup, podemos continuar sin peligro.

A continuación, marcamos la casilla "Expandir plantillas de artilugios", que nos permitirá acceder al código fuente completo de los Widgets, que son los elementos, bloques o controles que componen la interfaz de Blogger.

Una vez marcada esta casilla, podemos desplazarnos sobre el texto y buscar una porción de código similar a este, donde se ve claramente el comportamiento por defecto del gestor a la hora de mostrar el número de comentarios de una entrada:
  <b:if cond='data:post.numComments == 1'>
1 <data:commentLabel/>:
<b:else/>
<data:post.numComments/> <data:commentLabelPlural/>:
</b:if>


A simple vista se entiende el comportamiento por defecto del sistema, ¿no? Fijaos que se distingue cuando hay un único comentario para poner la etiqueta en singular, mientras que en resto de casos es en plural.

Si escudriñáis en el código de la plantilla, detectaréis que hay dos puntos donde aparece una porción similar. Uno de ellos es para indicar la presentación en la página principal de vuestro Blog, donde aparece la lista de los últimos posts; el otro es para la página individual de cada post. A efectos prácticos, lo que quiere decir es que podemos establecer reglas diferentes para cada caso, aunque por simplificar un poco el ejemplo no lo haremos aquí.

Pues bien, vamos a modificarlo ligeramente para animar al lector a participar en el blog con sus comentarios. Por cierto, no me gusta mucho moverme en el interior del textarea de Blogger. Prefiero llevarme el código a un editor de texto de mi equipo, y desde ahí manipularlo todo lo que quiera. Una vez he acabado de hacer los cambios, copio y pego sobre el cuadro de edición y listo; o si lo he salvado a mi disco, también podría subirse usando la opción de cargar o subir la plantilla disponible en la parte superior de la pantalla.

En cualquier caso, el nuevo código a incluir sería:
<b:if cond='data:post.numComments == 1'>
Ya hay 1 comentario, ¡participa!
<b:else />
<b:if cond='data:post.numComments == 0'>
No hay comentarios. ¡Sé el primero!
<b:else />
<data:post.numComments/> <data:commentLabelPlural/>:
</b:if>
</b:if>

Como se puede comprobar, si sólo hay un comentario lo indicamos y hacemos un llamamiento directo a la participación del usuario. Si no hay comentario alguno, animamos a ser el primero en comentar, y en el resto de los casos, hacemos como siempre.

Vamos, que ya no hay excusa para que en tu blog no haya participación. ;-D
miércoles, 6 de septiembre de 2006
Estoy estrenando Haloscan, un sistema on-line de gestión de comentarios y trackbacks para blogs. Se ha instalado él solito, sólo he tenido que indicarle mi usuario y contraseña de Blogger y él mismo ha insertado los cambios en la plantilla e incluso un post diciendo esto:

commenting and trackback
have been added to this blog.


En fin, a ver si alguien se anima y estrena el nuevo sistema haciendo un comentario, un trackback o lo que sea. Bueno, o mejor, para no esperar, los haré yo mismo.

La pena es que los comentarios que tenía hasta el momento, aunque eran escasos, todavía no sé muy bien dónde han ido a parar... tendré que investigar un poco.

martes, 16 de mayo de 2006
De vez en cuando surge algo que hace cambiar tu vida, tu forma de trabajar y de ver las cosas.

Casi me cuestra trabajo recordar cómo se trabajaba con MS-DOS, con una matriz de 80x25 caracteres chillones sobre fondo negro, interactuando sólo a base de pulsar teclas y (secretas) combinaciones de éstas. Existe un antes y un después de la llegada de los entornos gráficos, y más concretamente, de Windows como impulsor de este cambio.

También recuerdo la llegada de la revolución internet. Los que estábamos enganchados a las comunicaciones a través de las BBS y Fidonet (¡qué tiempos!) mirábamos recelosos esa nueva tecnología que prometía acceso instantáneo a casi ilimitada información, independientemente de la ubicación de ésta, servicios interactivos (chats), correo electrónico también casi instantáneo... Se puede imaginar la revolución que esto significaba en un mundo donde, a modo informativo, un mensaje personal enviado a través de Fidonet (netmails) podía tardar días, incluso semanas, en llegar a su destino; y por supuesto, nada de webs ni información hipertexto: los servicios se limitaban a foros y envío o recepción de archivos a servidores.

¡Y para qué hablar de la banda ancha! Es increíble cómo el mismo cable que conectábamos al flamante módem de 2400bps es capaz de mover ahora casi mil veces más información en el mismo tiempo, con un coste bastante razonable. ¡Esto sí que ha sido una revolución!

Y ahora que lo pienso, estos tres temas que he comentado se han producido cada cinco años, aproximadamente. Veamos... si partimos de que el paso de MS-DOS a Windows se produjo en la primera mitad de los noventa, la popularización de Internet en la segunda, y la de la banda ancha durante los años del nuevo siglo, podemos conjeturar que:

"Cada cinco años se produce la llegada de una tecnología, producto o filosofía de trabajo que revoluciona nuestras vidas"

Vale, admito que es un poco arriesgado. Pero hagamos una apuesta: si antes de finalizar el 2009 no ha surgido nada revolucionario en los términos que estoy describiendo, tenéis mi bendición para venir aquí y reventarme el buzón de correo a base de comentarios insultantes.

Ahí queda eso.
lunes, 8 de mayo de 2006
No se puede decir otra cosa... ¡ya era hora! Hace tiempo que observo desde mi atalaya cómo la forma de difusión de información a través de Internet ha ido evolucionando hasta llegar a este fenómeno que llamamos blog.

Y no puedo negar que siempre he sentido cierta envidia (sana, entiéndase) de aquellos que han tenido talento y tiempo suficiente para subirse al tren conforme éste iba comenzando a partir de la estación.

En cualquier caso, aunque ya en marcha, he decidido subirme al tren, y espero que el viaje sea largo. Pretendo firmemente, y suelo ser bastante tenaz en mis propósitos, que este diario recoja todo aquello que me llame la atención y mis reflexiones relativas a la tecnología en general, y al mundo del desarrollo de software en particular.

Nos vemos por aquí.