Cuando un recién llegado a PowerShell comienza a escribir scripts, normalmente se centra en el código. Después de todo, ¡el código es lo que hace que las cosas sucedan! El código ejecutable es obviamente importante, pero ¿qué pasa cuando escribes tanto código que te olvidas de lo que hace? Aquí es cuando los comentarios de PowerShell pueden entrar en juego.
Si estás en un equipo, ¿entienden el código que estás escribiendo? Los comentarios de PowerShell pueden ayudar.
Escribir comentarios de PowerShell descriptivos e informativos en los scripts nos ayuda a los humanos a entender la intención del código, el resultado, y quizás describe casos límite que se encontraron en un momento dado.
En este artículo, vas a conocer los diferentes tipos de comentarios en PowerShell, cuáles utilizar y cómo usarlos de forma efectiva en tus scripts.
Tabla de contenidos
¿Alguna vez has escrito algún código y has tenido que revisarlo semanas o meses después? Probablemente. Lo has entendido tanto tiempo después? Puede que no. Si al menos hubieras dejado algunos comentarios útiles en tu código!
La mayoría de los lenguajes de programación tienen el concepto de comentarios. PowerShell no es una excepción. En PowerShell, tu amigo es #. Todo lo que sigue al hashtag (#) en la misma línea es ignorado por PowerShell como código interpretado.
El código de ejemplo de abajo es un extracto de un script que… bueno, puedes consultar el comentario del script de PowerShell en la primera línea para saber qué hace. Si eres un experto en PowerShell, probablemente puedas señalar lo que hace este fragmento sin el comentario.
# Get all files with TXT extension, show the name of each file and then delete them.Get-ChildItem *.TXT | ForEach-Object { Write-Output $_.FullName Remove-Item $_.FullName}Pero, ¿qué pasa cuando te encuentras con un comando escueto como este de abajo?
"{0},{1}" -f (gm -input (1..20) -name count), (1..20).countAñadir comentarios te hará a ti o a cualquiera que eventualmente lea tu código un gran servicio. Como puedes ver a continuación, añadir un comentario encima del comando terse marca una gran diferencia a la hora de entender el código.
#Check whether the object has a property named "count". Then, return true or false."{0},{1}" -f (gm -input (1..20) -name count), (1..20).countEn la sección anterior, aprendiste que un comentario comienza con un carácter #. No hay nada que te impida crear varias líneas de comentarios. De hecho, antes de PowerShell 2.0, la única forma de crear comentarios de varias líneas es crear varias líneas de comentarios de una sola línea.
Es bueno mantener los comentarios breves y concisos, pero algunos escenarios exigen el uso de un comentario multilínea de PowerShell, que también puede denominarse bloque de comentarios de PowerShell.
Un bloque de comentarios en PowerShell comienza con <# y termina con #>. A continuación se muestran algunos ejemplos de cuándo es aplicable un bloque de comentarios.
Dividir un comentario largo en varias líneas
A veces es inevitable tener un comentario largo en un script. Estos comentarios largos pueden ir más allá de su marco actual de la pantalla. Cuando esto sucede, tendrá que seguir desplazándose horizontalmente para leer toda la línea de comentarios.
Por ejemplo, en lugar de tener un comentario largo de una sola línea como:
# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display. And when that happens, you will need to keep on scrolling horizontally to read the entire comment line.Por qué no convertirlo en un comentario de varias líneas que sea más fácil de leer como este de abajo:
<# It is sometimes unavoidable to have a long comment in a script. These long comments can go way beyond your current frame of the display.And when that happens, you will need to keep on scrolling horizontally to read the entire comment line. #>Añadir texto descriptivo
¿Alguna vez has descargado o escrito un script, y lo has guardado con un nombre aleatorio o no descriptivo? Yo sé que lo he hecho!
Cuando abres el script para saber qué demonios es, seguro que estaría bien que hubiera detalles útiles listados dentro como para qué es el script como quién lo creó y cuándo fue creado.
Un comentario de bloque en PowerShell es útil para añadir texto descriptivo en tus scripts. De esta manera, el propósito del script ya está dado y también es una gran manera de incluir advertencias o cosas a tener en cuenta cuando se utiliza el script.
A continuación se muestra un ejemplo de un comentario de bloque que describe lo que el script es, cuando se actualizó por última vez y también muestra una advertencia de lo que no se debe hacer al ejecutar el script.
<# Using this script will export the email addresses of all mailboxes in the Exchange organization.WARNING: DO NOT RUN THIS SCRIPT IN THE EXCHANGE MANAGEMENT SHELL.Last update: Feb 16, 2020#>Documentar requisitos y pasos
Si tu script tiene una forma específica de ejecutarse, o tiene requisitos especiales para ejecutarse, los comentarios de bloque ayudarían a documentarlo dentro de tu script o función.
A continuación se muestra un ejemplo de documentación de un requisito y pasos utilizando comentarios de bloque.
<#This function requires an encrypted credential XML file that will be usedto authenticate with Office 365.If you don't have this yet, follow these steps.1. Open PowerShell2. Run this command - 'Get-Credential | Export-CliXml .\credential.XML'3. Make sure to save the XML file inside the same folder as the script.NOTE: The credential XML file will only work on the same computer and the same accountused to generate it.#>Comentar código existente
Los comentarios se utilizan no sólo con el fin de añadir comentarios. También puede convertir las líneas de código existentes en comentarios de una sola línea o en bloque.
Tal vez se encuentre probando o depurando scripts. Cuando se comenta el código, PowerShell omite la ejecución de ese código durante el tiempo de ejecución.
Por ejemplo, tiene un script que obtiene una lista de usuarios en Active Directory, y esa lista se procesa utilizando el bucle foreach para establecer el nombre del departamento de cada usuario utilizando el cmdlet Set-AdUser.
<#This script will get all AD users matching the filterand each user's department name will be changed to 'Finance'.#>$adUsers = Get-ADUser -Filter *foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}Pero si quieres probar el bucle foreach sin ejecutar la línea Set-AdUser todavía, entonces sólo tienes que comentar esa línea en particular así:
foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" #Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'}Ahora el script puede ser probado con seguridad sin cambiar realmente el nombre del departamento de cada usuario.
TIP: En Visual Studio Code, puedes comentar una línea o varias líneas pulsando el atajo de teclado «CTRL + /».
Ahora bien, si quieres comentar varias líneas, tienes la opción de poner un # al principio de cada línea, o puedes encerrar varias líneas dentro del bloque <# #> como se muestra en el siguiente ejemplo. Como puede ver, todo el bucle foreach se ha convertido en un comentario de bloque.
$adUsers = Get-ADUser -Filter *<# foreach ($user in $adUsers) { Write-Output "$($user.Name) - Department name will be changed to 'Finance'" Set-AdUser -Identity ($user.SamAccountName) -Department 'Finance'} #>TIP: En Visual Studio Code, también puede crear un bloque de comentarios resaltando una línea o varias líneas de código y pulsando el atajo de teclado «ALT +SHIFT + A».
Comentarios.Based Help
Cuando quieras que tus scripts o funciones tengan un aspecto más profesional, puede hacerlo añadiendo ayuda basada en comentarios. Una ayuda basada en comentarios es una colección de palabras clave y textos encerrados en un bloque de comentarios.
Visita la página – Sobre la ayuda basada en comentarios – para saber más sobre la palabra clave y la sintaxis de la ayuda basada en comentarios.
El código de ejemplo que se muestra a continuación demuestra un script llamado Get-WhatTimeIsItNow.ps1, que tiene incluida una ayuda basada en comentarios.
<#.SYNOPSISShort description of the script.DESCRIPTIONLong description of the script.EXAMPLEPS C:\> Get-WhatTimeIsItNow.ps1Explanation of what the example does.INPUTSInputs (if any).OUTPUTSOutput (if any).NOTESGeneral notes#>Get-Date -Format tLa ayuda basada en comentarios permite Get-Help soportar sus scripts. Esto significa que cuando ejecute Get-Help <script/function>, PowerShell devolverá el texto de ‘ayuda’ contenido en su script como el que se muestra a continuación.
TIP: En Visual Studio Code, puedes insertar un bloque de ayuda basado en comentarios por defecto escribiendo comment-help en el panel del editor.
Mejores prácticas
Aquí hay algunas de las que se pueden llamar mejores prácticas para crear comentarios efectivos. No se trata en absoluto de requisitos estrictos, sino de recomendaciones que muchos ya ponen en práctica y que puedes utilizar como guía.
Cuando escribas código, puede que tengas la tentación de añadir una referencia a un número de línea en tus comentarios. Puede que tengas razón al pensar que añadir referencias al número de línea hace que tu código sea mucho más fácil de entender. Eso si estás seguro de que tu código nunca será modificado.
Imagina que se inserta una nueva línea de código en tu script. Esto significaría que todas las referencias de número de línea en sus comentarios ya se desplazaron. Y para mantener la numeración de líneas exacta, tendrás que editar los comentarios para actualizarlos uno a uno.
Los humanos estamos acostumbrados a leer de arriba a abajo. Si el comentario que estás añadiendo es importante para las siguientes líneas de código, entonces es lógico añadir los comentarios antes.
Después de todo, si estás añadiendo comentarios en el script sobre el script, ¿no es más sensato tener los comentarios antes del código y no después?
Al igual que el ejemplo anterior, poner los comentarios después del código, aunque sea en la misma línea, no es mejor que poner el comentario debajo del código.
Añadir comentarios al final del código puede provocar errores de edición porque en lugar de estar centrado en modificar el código, también tendrías que tener en cuenta que el comentario se mueve a lo largo del código.
No digas lo obvio
A veces el código es demasiado simple y la intención ya es demasiado obvia que añadir un comentario es un desperdicio. Generalmente en esta situación, un comentario podría ser incluso más largo que el código al que se refiere.
Si crees que el código se explica por sí mismo, puedes considerar omitir añadir un comentario.
Resumen
En este artículo, has aprendido la importancia de añadir comentarios a tus scripts o funciones de PowerShell. También has aprendido los diferentes tipos de comentarios disponibles y cómo un comentario correctamente elaborado y colocado puede aumentar significativamente la legibilidad de tu código.
No hay reglas duras y rápidas sobre cómo aplicar los comentarios en PowerShell, pero hay recomendaciones probadas y comprobadas sobre cómo usarlos. Al final, depende de ti cómo quieras utilizar los comentarios en tus scripts para recordarte las cosas cruciales desde el principio hasta el final.