c# – ¿Por qué y para qué comentas tu código?

Si alguna vez te has preguntado ¿Sirve de algo comentar el código? te recomiendo que leas el siguiente post.
Keep Calm
Keep Calm


Comencemos a hablar del tema citando la siguiente frase:

“Don’t comment bad code – rewrite it”
Brian W. Kernighan y P. J. Plaugher – The Elements of Programming style, 1978

Me llamo la atención la fecha de publicación del libro, desde 1978 se tenía el concepto de que no ayuda el tratar de explicar lo que el código hace, sino que la mejor solución es volverlo fácil de leer y entender.

Por otro lado, Uncle Bob nos dice lo siguiente acerca de los comentarios en su libro Clean Code:

La costumbre de usar comentarios es para compensar nuestra incapacidad de expresar lo que nuestro código hace. 

Finalmente, el blog coding horror nos dice esto:

El código te dice el cómo, los comentarios el porqué. (Code Tells You How, Comments Tell You Why)

Una de las más grandes motivaciones para agregar comentarios se debe a la forma errónea en que escribimos el código, todas estas malas prácticas se denominan Code Smells. Cuando terminamos de escribir una clase y vemos que no es fácil de entender, entonces decidimos que la mejor manera de ayudar a los demás a conocer lo que hemos hecho es agregando comentarios. Debemos tener en cuenta que el código claro y expresivo es mil veces mejor que un código complejo con muchos comentarios. En lugar de invertir nuestro tiempo escribiendo comentarios, deberíamos invertirlo en limpiar nuestro desorden.

1. ¿Qué tipos de comentarios debo evitar?
1.1 Redundantes, expresan lo que el código dice claramente (Genius):
public string Direccion { get; set; }//Propiedad Dirección
int t = 1;//Se asigna el valor 1 a la variable t
void CalcularSaldo()//Calcula el saldo
var usuario = new Usuario();//Crea una nueva instancia
//Constructor por defecto
public Util(){}
1.2 Obsoletos o desactualizados, son usados para despistar a la pobre alma que le toco darle mantenimiento:
//Solo ingresan si el valor es mayor a 20
if(valor > 100){}

/// <summary>
/// Envia un correo
/// </summary>
/// <param name="correo">Parametro correo</param>
/// <param name="formatoHtml">Formato Html</param>
void Enviar(string correo)
1.3 Mal redactados, demuestran el nivel God que tienen en gramática:
//Sy s mallor a 20 pazan
if(valor > 100){}
1.4 Esotéricos, se refugian en entidades divinas para poder entenderlos:
//When i wrote this, only God and I understood what I was doing.
//Now, only God Knows.
void PaymentGateway()
1.5 Traductores, sin ellos no se sabe lo que significa el código:
//Si el estado es Procesado = 3
if(usuario.Estado == 3){}
1.6 Ofrecen disculpas, saben lo que han hecho y se sienten culpables:
try
{
   servicioCorreo.EnviarNotificacion();
} 
catch(Exception ex){
//Este metodo a veces no funciona por eso esta dentro de un try-catch 
//para evitar que arroje un error 
}
1.7 Agresivos, advierten que nadie puede meterse con su cogido porque está bien escrito:
//No tocar-codigo muerde perro-virus/troyano
//fomat C:-blue screen of death
servicioCorreo.EnviarNotificacion();
1.8 Obligatorios, los que indican que toda clase, función, propiedad o variable debe tener un comentario:
/// <summary>
/// Contructor de la clase
/// </summary>
/// <param name="nombre">Parametro nombre</param>
/// <param name="apellido">Parametro apellido</param>
/// <param name="direccion">Parametro direccion</param>
public Util(string nombre, string apellido, string direccion)
{
}
1.9 Código comentado (Zombie Code), el que nunca quiere desaparecer y es considerado como un backup:
//servicioCorreo.EnviarNotificacion();
//servicioCorreo.EnviarNotificacionAdministrador();
//servicioCorreo.EnviarNotificacionSecretaria();
servicioCorreo.EnviarNotificacionEnCadena();
1.10 Marcadores, sirven para dividir las funcionalidades dentro de un método o una clase, ¿Alguien menciono el Principio de Responsabilidad única?:
//Registra los datos de una persona en la BD
public void Grabar()
{
//Envió de correo
//Código...
servicioCorreo.EnviarNotificacionEnCadena();

//Llamada a web service
//Código... 
servicioPoliza.CaducarPoliza("14521452488");

//Registro BD
//Código...
repositorioPoliza.ActualizarPoliza(poliza);
}
1.11 Bitácora, que lugar más seguro para registrar todos los cambios hechos si no es en el código ¿no?:
//Cambio 10/10/2001 - Se renombro el metodo
//Cambio 10/12/2012 - Se agrego un parametro nuevo
//Cambio 10/06/2014 - Se reemplazo el metodo, no funcionaba
servicioCorreo.EnviarNotificacionEnCadena();
1.12 Información de cabecera, hacen mucho y nada a la vez solo existen para que uses el scroll:
//***********************************************************
// Archivo : Repositorio.cs
// Autor : Alex Aldazabal
// Creado : 10/12/2012
// Resumen : Esta clase hace muchas cosas.
//***********************************************************
public class RepositorioPersona {}
1.13 Cierran llaves, para asegurarse que todos sepan dónde termina cada bloque de código:
try
{}
catch
{}//try-catch

while(true)
{}//while

if(true)
{}//if
1.14 Registran bugs, sirven para que otros no cometan los mismos errores:
//BUG: No se valido que la variable tenga un valor 10/12/2012
if(objeto != null) {}
1.15 Créditos, por si alguien se quiere volver conocido:
//Agregado por laldazabal
if(objeto != null) {}
1.16 Emoticones, para hacer el código más sociable:
//;-) B-) :-S :-@
if(objeto != null) {}
1.17 Divertidos, te hacen reír para que se te pase por un momento el estrés:
//Dear manteiner:
//So if you are done trying to 'optimize'
//this routine (and failed),
//please increment the folowing counter
//as a warning
//to the next guy:
//total_hours_wasted_here = 76;
void PaymentGateway()
2. Entonces, ¿Qué tipos de comentarios debo usar?
2.1 Agregan información adicional:
//formato esperado kk:mm:ss EEE, MMMM, dd, yyyy
var timeMatcher = Pattern.Compile("\\d*:\\d*:\\d*\\w*,\\w*\\d*,\\d*");
2.2 Indican una decisión:
//Se trabajo con el objeto StringBuilder en lugar del string
//porque tiene mejor rendimiento
//Referencia: http://support.microsoft.com/kb/306822
var builder = new StringBuilder();
foreach(var mensaje in listaMensajes)
{
    builder.Append(mensaje);
}
2.3 Advierten alguna consecuencia:
//Si se lanza una prueba en el ambiente de producción 
//el banco penalizara a la empresa
public void TransferirSaldo(string origen, string destino, double monto)
2.4 TODO (Tareas por realizar):
//TODO: Agregar la validación de los parámetros de entrada
public void TransferirSaldo(string origen, string destino, double monto)
2.5 Resaltan la importancia de una decisión:
//Es importante eliminar los espacios en blanco debido a que el servicio 
//no los reconoce como caracteres validos
numeroCuenta = numeroCuenta.Trim();
AumentarLineaCredito(numeroCuenta);
Conclusión

El mejor tipo de comentario es el que no se necesita ;).

Si te gusto este post entonces por favor ayúdame a difundirlo y logremos que el conocimiento se expanda, para lograr esto dale me gusta, compártelo en tus redes sociales a tus amigos o suscríbete a mi canal RSS, Gracias :).
Referencias:
Metal Tip:

Este artículo lo escribí escuchando la canción Resurrection de la banda de Halford de Inglaterra donde canta el vocalista de Judas Priest, les comparto el enlace.

Happy coding and Stay Heavy lml

Anuncios

4 comentarios en “c# – ¿Por qué y para qué comentas tu código?

      1. Muchas gracias, me da mucho gusto que estos artículos les sean de utilidad. Comentarios como este me animan a escribir mas 😉

        Me gusta

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s