Cursos Empresas Blog Live Conf Eventos Precios

0:009:10

Recursos

Resumen

¿Cómo utilizar correctamente los comentarios en el código?

Los comentarios en el código son elementos esenciales que, cuando se utilizan adecuadamente, facilitan la comprensión y el mantenimiento del software. Sin embargo, pueden convertirse en un obstáculo si se abusa de ellos o si se emplean de manera redundante. A lo largo de esta guía, exploraremos las prácticas recomendadas para el uso de comentarios, a fin de escribir código limpio y eficiente.

¿Qué tipo de comentarios deben evitarse?

El exceso de comentarios es uno de los problemas más comunes. Los comentarios que simplemente repiten lo que ya se indica en el código son redundantes y aumentan la complejidad visual sin agregar valor real. Aquí algunas prácticas que se deben evitar:

Comentarios obvios: No comentes lo que ya es evidente por el nombre de la clase, método o variable. Por ejemplo, si tienes un método llamado calcularPromedio, no es necesario agregar un comentario que diga "calcula el promedio".
Comentarios sin propósito: No agregues comentarios para cosas temporales, como dejar código comentado con la intención de utilizarlo más adelante. Eso suele volverse permanente por descuido.
Comentarios sobre cambios: Los sistemas de control de versiones como Git llevan un historial de los cambios. No es necesario documentar cada modificación en el código con comentarios.

¿Cuándo son útiles los comentarios?

A pesar de que lo ideal es tener código autoexplicativo, en situaciones específicas los comentarios pueden añadir un contexto valioso.

Código complejo: En casos donde el código es inevitablemente intrincado, como el uso de expresiones regulares complejas, los comentarios pueden ayudar a aclarar lo que sucede.
Justificación de decisiones: Si se deben tomar decisiones no obvias, como modificar índices de un array, es útil documentar el porqué detrás de esa elección.

Por ejemplo:

// Disminuir una posición, ya que el array comienza en cero
arrayIndex = userInput - 1;

¿Cómo deberían ser los comentarios efectivos?

Un buen comentario no debe restar claridad al código, sino contribuir a su entendimiento. Algunas recomendaciones para lograrlo incluyen:

Asegúrate de que sean breves y claros. Evita comentarios extensos; en lugar de eso, busca que sean directos y precisos.
Haz uso de bloques estructurados si es necesario. Por ejemplo, cuando documentas funciones, puedes utilizar anotaciones tipo summary si estas ofrecen información útil al invocar el método.
Revisar y eliminar comentarios innecesarios. Al mantener tu código, asegúrate de que los comentarios sigan siendo relevantes y elimínalos si ya no aportan valor.

¿Cómo aplicar estas prácticas en código específico?

En el proyecto de ejemplo, observamos diferentes casos de comentarios y cómo se implementaron las mejoras.

Por ejemplo, en un método que retorna la opción seleccionada por el usuario, un comentario bien estructurado puede ser útil si contiene un resumen y una lista de las opciones disponibles:

/// <summary>
/// Muestra las opciones de tareas disponibles.
/// </summary>
/// <returns>Retorna la opción seleccionada por el usuario</returns>

Por otro lado, comentarios como:

// read line

No son necesarios cuando la operación es clara debido al nombre de la variable o función.

En este contexto, la mejora en el código implica no solo agregar comentarios útiles sino también eliminar aquellos que no aportan claridad y podrían obstaculizar la comprensión del código.

Implementar estas buenas prácticas en tus proyectos personales no solo mejorará la calidad de tu código sino que facilitará su mantenimiento y evolución a lo largo del tiempo. Te invito a reflexionar sobre los comentarios en tus proyectos actuales y a optar siempre por la claridad y el minimalismo a la hora de documentar tu código.

Buenas Prácticas para Comentarios en Código Fuente

Curso de Buenas Prácticas y Código Limpio en C#

Clase 13 de 14

Clase 13 / 14

Francisco Javier Tejada Lorenzo

Hace 3 años

Recomendaciones para comentar:

No abuses de los comentarios.
Si los comentarios son obvios, no los pongas.
Escribe código fácil de entender como filosofía.
No comentes la trazabilidad de cambios (eso lo debería hacer el controlador de versiones que estemos utilizando, por ejemplo git, github etc...).
Mantén los comentarios cortos y claros.
No dejes código comentado.

Jose Roque

Hace 2 años

mi Código minimalismo List<string> TaskList = new List<string>(); optionMenu optionMenu;do{ optionMenu = (optionMenu)ShowMainMenu(); if (optionMenu == optionMenu.Add) { ShowMenuAdd(); } else if (optionMenu == optionMenu.Remove) { ShowMenuRemove(); } else if (optionMenu == optionMenu.List) { ShowMenuPrintList(); }} while (optionMenu != optionMenu.Exit);

void PrintRepeatCharacter(char caracter, int size) => Console.WriteLine(new String('-', 40)); ``/// <summary>`` ``/// Show the main menu `` ``/// </summary>`` ``/// <returns>Returns option indicated by user</returns>`` int ShowMainMenu() { int line=-1; do{ try{ PrintRepeatCharacter('-',40); Console.WriteLine("Ingrese la opción a realizar: "); Console.WriteLine("1. Nueva tarea"); Console.WriteLine("2. Remover tarea"); Console.WriteLine("3. Tareas pendientes"); Console.WriteLine("4. Salir"); string input = Console.ReadLine(); ``// Read line`` if (!int.TryParse(input, out line)) { Console.WriteLine("La entrada no es un número entero válido."); line = -1; } }catch{ line = -1; } }while(line<=0 || line>4); return line; } void ShowMenuRemove() { try { Console.WriteLine("Ingrese el número de la tarea a remover: "); ShowMenuPrintList(); string line = Console.ReadLine(); ``// Remove one position`` int indexToRemove = Convert.ToInt32(line) - 1; if(indexToRemove<0 || indexToRemove>(TaskList?.Count-1)) Console.WriteLine("# de tarea ingresada es inválida"); else { string task = TaskList[indexToRemove]; TaskList.RemoveAt(indexToRemove); Console.WriteLine($"Tarea {task} eliminada"); } } catch (Exception) { System.Console.WriteLine("Ocurrio un Error al intentar Eliminar una Tarea"); } } void ShowMenuAdd() { try { Console.WriteLine("Ingrese el nombre de la tarea: "); string task = Console.ReadLine(); TaskList.Add(task); Console.WriteLine("Tarea registrada"); } catch (Exception) { System.Console.WriteLine("Error al recibir nombre de la tarea"); } } void ShowMenuPrintList() { if (TaskList?.Count == 0) { Console.WriteLine("No hay tareas por realizar"); } else { PrintRepeatCharacter('-',40); int indexItem=0; TaskList.ForEach(p=>Console.WriteLine($"{++indexItem}. {p}")); PrintRepeatCharacter('-',40); } } internal enum optionMenu { Add = 1, Remove = 2, List = 3, Exit = 4 }

Jose Roque

Hace 2 años

mi código mini

List<string> TaskList  = new List<string>();

optionMenu optionMenu;
do
{
    optionMenu = (optionMenu)ShowMainMenu();
    if (optionMenu == optionMenu.Add)
    {
        ShowMenuAdd();
    }
    else if (optionMenu == optionMenu.Remove)
    {
        ShowMenuRemove();
    }
    else if (optionMenu == optionMenu.List)
    {
        ShowMenuPrintList();
    }
} while (optionMenu != optionMenu.Exit);


    void PrintRepeatCharacter(char caracter, int size) => Console.WriteLine(new String('-', 40));

    /// <summary>
    /// Show the main menu 
    /// </summary>
    /// <returns>Returns option indicated by user</returns>
    int ShowMainMenu()
    {
        int line=-1;
        do{
            
            try{
                PrintRepeatCharacter('-',40);
                Console.WriteLine("Ingrese la opción a realizar: ");
                Console.WriteLine("1. Nueva tarea");
                Console.WriteLine("2. Remover tarea");
                Console.WriteLine("3. Tareas pendientes");
                Console.WriteLine("4. Salir");
                
                string input = Console.ReadLine();
                // Read line
                if (!int.TryParse(input, out line))
                {
                    Console.WriteLine("La entrada no es un número entero válido.");
                    line = -1;
                }
            }catch{
                line = -1;
            }
        }while(line<=0 || line>4);

        return line;
    }

    void ShowMenuRemove()
    {
        try
        {
            Console.WriteLine("Ingrese el número de la tarea a remover: ");
            ShowMenuPrintList();

            string line = Console.ReadLine();
            // Remove one position
            int indexToRemove = Convert.ToInt32(line) - 1;
            if(indexToRemove<0 || indexToRemove>(TaskList?.Count-1))
                Console.WriteLine("# de tarea ingresada es inválida");
            else
            {
                string task = TaskList[indexToRemove];
                TaskList.RemoveAt(indexToRemove);
                Console.WriteLine($"Tarea {task} eliminada");
            }
        }
        catch (Exception)
        {
            System.Console.WriteLine("Ocurrio un Error al intentar Eliminar una Tarea");
        }
    }

    void ShowMenuAdd()
    {
        try
        {
            Console.WriteLine("Ingrese el nombre de la tarea: ");
            string task = Console.ReadLine();
            TaskList.Add(task);
            Console.WriteLine("Tarea registrada");
        }
        catch (Exception)
        {
            System.Console.WriteLine("Error al recibir nombre de la tarea");
        }
    }

    void ShowMenuPrintList()
    {
        if (TaskList?.Count == 0)
        {
            Console.WriteLine("No hay tareas por realizar");
        } 
        else
        {
            PrintRepeatCharacter('-',40);
            int indexItem=0;
            TaskList.ForEach(p=>Console.WriteLine($"{++indexItem}. {p}"));
            PrintRepeatCharacter('-',40);
        }
    }

      internal enum optionMenu {
        Add = 1,
        Remove = 2,
        List = 3,
        Exit = 4
    }
```Archivo ToDo.csproj
```js
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>EXE</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

```**Gracias por el repaso.**

Comentarios (9)9 comentarios

David Elias Gatica Morales

No Comentes mal código, reescribelo

Jesús Leonardo Perea Alarcón

Hace 4 años

cual es la mejor practica, comentarios en ingles o en español ?

Miguel Teheran

Profesor

Todo deberia ser en ingles, pero depende de como lo manejen en el proyecto o empresa donde estes. Lo importante es seguir el estandar en toda parte.

Leandro Cosme Tomassini

Uso de comentarios en C#

¿Qué son?

Los comentarios son anotaciones en el código que no se ejecutan por el compilador. Se utilizan para:

Explicar el código: Ayudan a comprender el propósito del código.
Documentar el código: Proporcionan información sobre el código, como su autor, fecha de creación, modificaciones, etc.
Mejorar la legibilidad del código: Ayudan a estructurar y organizar el código.

Tipos de comentarios en C#:

Comentarios de una sola línea: Comienzan con dos barras diagonales (//) y terminan al final de la línea.
Comentarios de varias líneas: Comienzan con una barra diagonal y un asterisco (/*) y terminan con un asterisco y una barra diagonal (*/).

Beneficios de usar comentarios:

Mejora la comprensión del código.
Facilita el mantenimiento del código.
Permite la colaboración entre diferentes desarrolladores.

Consejos para usar comentarios:

Utiliza un lenguaje claro y conciso.
Evita los comentarios redundantes.
Actualiza los comentarios cuando se modifica el código.

// Este es un comentario de una sola línea.

/* Este es un comentario
de varias líneas. */

Juan Pablo Ruiz

no hay que sobre cargar de comentarios nuestros desarrollos, ya que generan mucha ilegibilidad.

edward.arroyave

Me surgió una inquietud acerca del código comentado. En algunas situaciones, se realiza una modificación en alguna estructura del código y se comenta la estructura anterior. Al revisar proyectos en los que necesito hacer ajustes, noto que hay numerosos scripts comentados. ¿Sería recomendable eliminarlos o es preferible dejar que permanezcan?

Eliminarlos, el código comentado ensucia la lectura. a veces dejan esos código temporalmente y luego terminan quedandose.

Miguel Andres Rendon Reyes

Me preguntaba, si hay herramientas externas para documentar el código, para que se pueda explicar en profundidad.

Ahora mismo la mejor opción es usar github copilot chat para generar todo de manera automatica. LA idea es agregar el menor numero de comentarios obvios y enfocarse en mejorar el código en si para que sea fácil de entender y leer.

JUAN ESTEBAN MORENO NORIEGA

IMPORTANTE

En ocasiones solemos imprimir en consola información. Esto es importante a la hora de desarrollar; pero es fundamental que a la hora de desplegar nuestro proyecto eliminar los debugs que no sean necesarios, generan problemas de seguridad a la hora de algun ataque. Además, dejar comentado código que no vamos a utilizar, puede generar que desde alguna pagina web o aplicación esto pueda verse y no tener sentido alguno, generando nuevamente problemas de seguridad,

Miguel Angel Reyes Moreno

Recursos

Resumen

Buenas Prácticas para Comentarios en Código Fuente

Progreso del curso

Introducción

Principios del código limpio

Mejoras en C# y comentarios

Cierre