Ejercicio: Creación de comentarios de código efectivos

13 minutos

En este ejercicio, agregaremos notas a nuestro código y deshabilitaremos temporalmente ciertas líneas de código de la compilación. A continuación, veremos cómo el compilador de C# entiende los espacios en blanco y cómo usarlos para aumentar la legibilidad del código.

¿Qué es un comentario de código?

Un comentario de código es una instrucción del compilador para omitir todo lo que aparece después de los símbolos de comentario de código en la línea actual.

// This is a code comment!

Es posible que esto no parezca útil a primera vista, pero es útil en tres situaciones:

Si quiere dejar una nota sobre la intención de un fragmento de código. Puede resultar útil incluir comentarios de código para describir el propósito o el razonamiento cuando está escribiendo un conjunto de instrucciones de codificación especialmente complejo. Su futuro yo se lo agradecerá.
Si quiere quitar temporalmente el código de la aplicación para probar un enfoque diferente, pero aún no está convencido de que la nueva idea funcionará. Puede marcar como comentario el código, escribir el código nuevo y, una vez que esté convencido de que el nuevo código funcionará de la manera que quiere, puede eliminar de forma segura el antiguo (el código comentado).
Si quiere agregar un mensaje como TODO para acordarse de revisar un fragmento de código determinado más adelante. Aunque debe usarlo con prudencia, es un enfoque útil. Es posible que esté trabajando en otra característica y lea una línea de código en la que detecta un problema. En lugar de omitir el nuevo problema, puede marcarlo para investigarlo más adelante.

Nota

Los comentarios de código deben usarse para indicar lo que el código no puede hacer. A menudo, los desarrolladores actualizan su código, pero se olvidan de actualizar los comentarios de código. Es mejor usar los comentarios para ideas de nivel superior y no agregar comentarios sobre cómo funciona una línea de código individual.

Preparación del entorno de creación de código

En este módulo se incluyen ejercicios que le guiarán por el proceso de compilación y ejecución de código de ejemplo. Se recomienda realizar las actividades con Visual Studio Code como entorno de desarrollo. El uso de Visual Studio Code para estas actividades le ayudará a familiarizarse con la escritura y la ejecución de código en un entorno de desarrollador que usan los profesionales de todo el mundo.

Abra Visual Studio Code.

Puede usar el menú Inicio de Windows (o un recurso equivalente para otro sistema operativo) para abrir Visual Studio Code.
En Visual Studio Code, en el menú Archivo, seleccione Abrir archivo.
En el cuadro de diálogo Abrir carpeta, vaya a la carpeta Escritorio de Windows.

Si tiene una ubicación de carpeta diferente donde guarda los proyectos de código, úsela. Para este curso, lo importante es tener una ubicación fácil de encontrar y recordar.
En el cuadro de diálogo Abrir carpeta, elija Seleccionar carpeta.

Si ve un cuadro de diálogo de seguridad en el que se le pregunta si confía en los autores, seleccione Sí.
En Visual Studio Code, en el menú Terminal, seleccione Nuevo terminal.

Observe que un símbolo del sistema en el panel Terminal muestra la ruta de acceso de la carpeta actual. Por ejemplo:
```
C:\Users\someuser\Desktop>
```
Nota

Si está trabajando en su propio equipo, en lugar de en un entorno aislado u hospedado, y ha realizado otros módulos de Microsoft Learn de esta serie de C#, es posible que ya haya creado una carpeta de proyecto para ejemplos de código. Si ese es el caso, puede saltar al paso siguiente, que se usa para crear una aplicación de consola en la carpeta TestProject.
En el símbolo del sistema de Terminal, para crear una nueva aplicación de consola en una carpeta especificada, escriba el símbolo del sistema siguiente:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Este comando de la CLI de .NET usa una plantilla de programa de .NET para crear un nuevo proyecto de aplicación de consola de C# en la ubicación de carpeta especificada. El comando crea las carpetas CsharpProjects y TestProject y usa TestProject como nombre del archivo .csproj.

Si se muestra un mensaje que indica que los archivos ya existen, continúe con los pasos siguientes. Reutilizará los archivos de proyecto existentes.
En la vista EXPLORER, expanda la carpeta CsharpProjects .

Debería ver la carpeta TestProject y dos archivos, un archivo de programa de C# denominado Program.cs y un archivo de proyecto de C# denominado TestProject.csproj.
En Visual Studio Code, en el menú Archivo, seleccione Abrir archivo.
En el cuadro de diálogo Abrir carpeta , seleccione la carpeta CsharpProjects y, a continuación, seleccione Seleccionar carpeta.
En la vista EXPLORER, expanda la carpeta TestProject y, a continuación, seleccione Program.cs.
Elimine las líneas de código existentes.

Usará este proyecto de consola de C# para crear, compilar y ejecutar ejemplos de código durante este módulo.
Cierre el panel del terminal.

Creación y uso de comentarios de código

En esta tarea, creará y eliminará varios tipos de comentarios de código.

En el panel editor de Visual Studio Code, escriba el código siguiente:

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

Para modificar el código con comentarios y revisiones de código, actualice el código de la siguiente manera:

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Dedique un minuto a revisar los comentarios y las actualizaciones de código.

Tenga en cuenta que los comentarios de código se han usado para documentar un posible cambio que se va a realizar y para deshabilitar temporalmente el mensaje anterior mientras se prueba el nuevo. El siguiente paso será probar la actualización. Si está satisfecho con el nuevo código, podemos eliminar de forma segura el código anterior que se ha marcado como comentario. Se trata de un enfoque más seguro y metódico para modificar el código de trabajo hasta que está convencido de que está a punto para quitarlo de forma permanente.
En el menú Archivo de Visual Studio Code, haga clic en Guardar.
En la vista EXPLORER, para abrir un terminal en la ubicación de la carpeta TestProject, haga clic con el botón derecho en TestProject y, a continuación, seleccione Abrir en terminal integrado.
En el símbolo del sistema del terminal, guarde el trabajo, escriba dotnet run y presione Entrar.

Debería ver la siguiente salida:
```
Bob purchased 7 widgets.
```
De nuevo, si está satisfecho con las actualizaciones, elimine el código antiguo que se ha marcado como comentario.

Elimine los comentarios de código.

El código debería coincidir con este de aquí:

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Para aplicar un comentario de bloque que marca varias líneas como comentario, actualice el código de la siguiente manera:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Los comentarios de bloque son excelentes si necesita escribir un comentario largo o quitar muchas líneas de código. Los comentarios de bloque usan /* al principio del código y */ al final. Usar un comentario de bloque es la forma más rápida y sencilla de deshabilitar tres líneas de código o más.

Reemplace el código existente por el siguiente:

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Nota

Hay muchos conceptos de C# en esta lista de códigos que pueden ser nuevos para usted. No es necesario que entienda lo que hace el código para apreciar cómo los comentarios pueden ayudar a los lectores a comprender el propósito del código.

Tómese un minuto para ver si puede averiguar el propósito del código.

Gracias a los comentarios, es posible que pueda averiguar lo que hace el código (en caso de que los comentarios describan con precisión el estado actual y se actualizasen a la vez que el código). Pero ¿puede adivinar para qué es este código? ¿No sería útil si hubiera una explicación en la parte superior del archivo de código que proporcionara un contexto y describiera el propósito?
Piense en cómo mejoraría los comentarios.

Observe que hay dos problemas principales con estos comentarios:
- Los comentarios de código explican innecesariamente la funcionalidad obvia de las líneas de código individuales. Se consideran comentarios de baja calidad porque simplemente explican cómo funcionan C# o los métodos de la biblioteca de clases .NET. Si el lector no está familiarizado con estas ideas, puede buscarlas en learn.microsoft.com o IntelliSense.
- Los comentarios de código no proporcionan ningún contexto sobre el problema que resuelve el código. Se consideran comentarios de baja calidad porque el lector no obtiene información sobre el propósito de este código, especialmente en lo que se refiere al sistema en general.

Quite los comentarios existentes.

El código debería coincidir con este de aquí:

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Observe que el código ya está menos desordenado.

Para agregar un comentario que explique el propósito de nivel superior del código, actualice el código de la siguiente manera:

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

La utilidad de un comentario es subjetiva. En todas las cuestiones relacionadas con la legibilidad del código, debe basarse en su mejor juicio. Haga lo que considere que es más adecuado para mejorar la claridad del código.

Resumen

Puntos clave de este ejercicio:

Use los comentarios de código para dejar notas significativas sobre el problema que resuelve el código.
No use comentarios de código que expliquen cómo funcionan C# o la biblioteca de clases .NET.
Use los comentarios de código para probar temporalmente soluciones alternativas hasta que esté listo para confirmar la nueva solución de código, en cuyo momento, puede eliminar el código anterior.
No confíe nunca en los comentarios. Es posible que no reflejen el estado actual del código después de muchos cambios y actualizaciones.

Ejercicio: Creación de comentarios de código efectivos

¿Qué es un comentario de código?

Preparación del entorno de creación de código

Creación y uso de comentarios de código

Resumen

Comentarios