Buenas Prácticas para Comentarios en Código Fuente

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

Contenido del curso

Introducción

Principios del código limpio

Mejoras en C# y comentarios

Cierre

14
Buenas Prácticas y Código Limpio en C-Sharp
05:08 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:009:10

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

Recursos

¿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.

Francisco Javier Tejada Lorenzo

Hace 2 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.**

Introducción

Buenas prácticas y código limpio en C-Sharp

Prerrequisitos para código limpio en C#

Buenas Prácticas y Código Limpio en Desarrollo de Software

Descarga y explora el proyecto base en C#

Principios del código limpio

Buenas prácticas de nombres en C#

Identificación de Co-Smells en C-Sharp y Soluciones Prácticas

Principio DRY aplicado en C#

Principio KISS aplicado en C#

Buenas prácticas de uso de try-catch en C#

Mejoras en C# y comentarios

Evolución de C# de la versión 6 al 10

Interpolación de cadenas y mejoras en C-Sharp

Mejoras de Sintaxis y Minimalismo en C# utilizando .NET 6

Buenas Prácticas para Comentarios en Código Fuente

Cierre

Buenas Prácticas y Código Limpio en C-Sharp

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

Recursos

Recursos