El rincón de JMACOE

¿Alguna vez has revisado el código y has encontrado un comentario que consideras innecesario? Comentar se hace con la intención de mejorar la legibilidad del código y hacerlo más comprensible para alguien que no sea el desarrollador original.

He identificado 5 tipos de comentarios que realmente molestan y los tipos de desarrolladores que los hacen. Espero que después de leer esto no caerás en alguna de estas categorías.

1. El programador orgulloso

public class Program
{
    static void Main(string[] args)
    {
        string message = "Hola Mundo!";  // 07/24/2010 Bob
        Console.WriteLine(message); // 07/24/2010 Bob
        message = "Estoy tan orgulloso de este código!"; // 07/24/2010 Bob
        Console.WriteLine(message); // 07/24/2010 Bob
    }
}

Este programador es tan orgulloso de su código que siente la necesidad de etiquetar cada línea de código con sus iniciales. La implementación de un sistema de control de versions (VCS) permite la rendición de cuentas en los cambios de código, pera primera vista no será tan evidente quién es responsable.

2. El programador obsoleto

public class Program
{
    static void Main(string[] args)
    {
        /* Este bloque de código no es necesario
         * debido a que nos encontramos fuera del engaño del Y2K 
         * y nuestros sistemas no volverán al 1/1/1900 */
        //DateTime today = DateTime.Today;
        //if (today == new DateTime(1900, 1, 1))
        //{
        //    today = today.AddYears(100);
        //    string message = "Esta fecha a sido corregida para el Y2K.";
        //    Console.WriteLine(message);
        //}
    }
}

Si una porción de código ya no se utilize (es decir, obsoletos), proceda a su eliminación – no satures tu código de trabajo con muchas líneas de comentarios innecesarios. Además, si alguna vez tiene que repetir el código eliminado tienes un sistema de control de versiones, para que puedas recuperar el código desde una versión anterior.

3. El programador evidente

public class Program
{
    static void Main(string[] args)
    {
        /* Este es un bucle for que imprime las 
         * palabras "I Rule!" en la consola de la pantalla
         * 1 millón de veces, cada una en su propia línea. 
         * Se lleva a cabo empezando en 0 y con 
         * incrementos de 1. Si el valor del contador
         * es igual a 1 millón el bucle for termina
         * su ejecución.*/
        for (int i = 0; i < 1000000; i++)
        {
            Console.WriteLine("I Rule!");
        }
    }
}

Todos sabemos cómo funciona la lógica de programación básica – no se trata de «Introducción a la programación». No es necesario perder el tiempo explicando cómo funciona lo evidente, y nos alegra que puedas explicar cómo funciona el código – pero es una pérdida de espacio.

4. El programador historia de la vida

public class Program
{
    static void Main(string[] args)
    {
       /* Yo discutí con Jim de Ventas sobre el café
        * en Starbucks en la calle principal un día y me
        * contó que las comisión que perciben los representantes 
        * de ventas se basan en la siguiente estructura. 
        * Viernes: 25%
        * Miercoles: 15%
        * Los demás días: 5%
        * ¿Mencioné que ordené el Latte Caramelo con
        *  una dosis doble de café espresso? 
       */
        double price = 5.00;
        double commissionRate;
        double commission;
        if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
        {
            commissionRate = .25;
        }
        else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
        {
            commissionRate = .15;
        }
        else
        {
            commissionRate = .05;
        }
        commission = price * commissionRate;
    }
}

Si se tienes que mencionar los requerimientos en tus comentarios, no menciones los nombres de las personas. Jim de Ventas probablemente se retiro de la empresa y lo mas probable es que los programadores que leerán esto no sabrán quien es. Por no mencionar el hecho que todo lo demás en el comentario es irrelevante.

5. El programador algún día

public class Program
{
    static void Main(string[] args)
    {
       //PARA HACER: Necesito arreglar esto algún día – 07/24/1995 Bob
       /* Se que el mensaje de error es difícil de codificar y 
        * confió en  la función Contains, pero algún día
        * yo haré que este código imprima un mensaje 
        * significativo y gracioso.
        * Simplemente no tengo tiempo ahora.
       */
       string message = "Un error ha ocurrido.";
       if(message.Contains("error"))
       {
           throw new Exception(message);
       }
    }
}

Este tipo de comentario es una especie de cajón de sastre que combina todos los otros tipos. El comentario PARA HACER puede ser muy útil cuando se estás en las etapas iniciales de desarrollo de tu proyecto, pero si esto aparece varios años más adelante en el código de producción – puede significar problemas. Si algo necesita ser arreglado, arreglalo ahora y no lo dejes para más tarde.

Si eres uno de los que hace estos tipos de comentarios o le gustaría aprender las mejores prácticas en el uso de comentarios, recomiendo la lectura de un libro como Code Complete de Steve McConnell. O tal vez si aprendes como dejar de comentar tu código por completo.