1.1K
Casi todos los lenguajes de programación tienen una forma de agregar comentarios al código y PowerShell no es una excepción. Cuando escribe código en PowerShell, puede que le resulte útil agregar comentarios para explicar lo que hace su código.
Comentar el código es una práctica estándar al probar y depurar para que esa parte del código no se ejecute. Hay dos tipos de estructuras de comentarios en PowerShell: línea y bloquear.
Cada tipo tiene su propósito, pero ambos se pueden usar indistintamente.
En este tutorial, explicaremos cómo comentar el código de PowerShell, incluida la creación de ayuda basada en comentarios para agregar ayuda integrada a sus scripts.
Comentarios de una sola línea
Los comentarios de una sola línea o de una línea usan una lógica simple: todo lo que sigue al # se ignora el signo en la misma línea.
Vea el código de ejemplo a continuación:
# Get-Service | Select-Object -First 5 Get-Process | Select-Object -First 5
El código anterior tiene dos líneas. La primera línea está comentada y, como resultado, PowerShell la ignorará y no se ejecutará.
Otra forma de usar comentarios de línea es al final de la línea:
Get-Process | Select-Object -First 5 # Return the first five processes.
Puede combinar los comentarios de línea arriba y después de la línea como el código a continuación. El primer comentario en la parte superior describe lo que hace el bloque de código, mientras que los comentarios al final de la línea describen la línea de código específica.
# Define the certificate details
$certSplat = @{
Subject="CN=MailboxQuotaStatus" # Certificate subject
NotBefore = ((Get-Date).AddDays(-1)) # Validity start date
NotAfter = ((Get-Date).AddYears(5)) # Expiration date
CertStoreLocation = "Cert:\CurrentUser\My" # Certificate store location
KeySpec = "KeyExchange" # Key usage
Provider="Microsoft Enhanced RSA and AES Cryptographic Provider" # Encryption provider
}
# Create the Self-Signed certificate
New-SelfSignedCertificate @certSplat
si estás usando código de estudio visual para escribir su código, puede presionar CTRL+/ para comentar la línea actual.
O varias líneas.
Nota. Consulte nuestro tutorial sobre cómo enviar correos electrónicos con el cmdlet de PowerShell Enviar MailMessage.
Bloquear comentarios
A diferencia de los comentarios de línea, los comentarios de bloque encierran una o más líneas entre <# y #>. PowerShell ignorará todo lo que se encuentre dentro de estas marcas de inicio y cierre. Este tipo de comentario tiene más sentido en algunos casos de uso.
Además de comentar el código, puede usar esto para dividir un comentario muy largo en varias líneas. A continuación se muestra un ejemplo de un comentario largo en una sola línea:
# This is a very long comment that spans outside the display capacity and goes out of view making it really hard to read.
Los comentarios largos pueden ser difíciles de leer porque te obligan a desplazarte de lado a lado. Para que sea más fácil de leer, puede convertirlo en un comentario de bloque y ajustarlo en un marco más estrecho.
<# This is a very long comment that spans outside the display capacity and goes out of view making it really hard to read. #>
Otro uso excelente de los comentarios en bloque es tener documentación en el código. Por ejemplo, puede incluir instrucciones previas a la ejecución dentro del script.
<# Before running this script, ensure to do the following preparations: 1. Do this. 2. Do that. 3. Then whatever. #>
También puede usar un comentario de bloque para incrustar detalles en una línea de código sin romper el código.
Get-Service -Name <# service name here #> ProfSvc
Como puede ver, incluso si el comentario del bloque está incrustado en la línea, PowerShell lo omite y el comando continúa ejecutándose correctamente.
En Visual Studio Code, puede resaltar una línea o varias líneas y presionar MAYÚS+ALT+A para convertirlo en un bloque de comentarios.
Ayuda basada en comentarios
¿Alguna vez te has preguntado cómo algunos comandos integrados tienen sistemas de ayuda? Por ejemplo, Obtener-Ayuda-Nombre Obtener-Contenido le muestra el sistema de ayuda para el cmdlet Get-Content.
Puede crear el mismo sistema de ayuda para sus secuencias de comandos y funciones utilizando la ayuda basada en comentarios. La ayuda basada en comentarios tiene la forma de un comentario de bloque pero con una sintaxis definida. A continuación se muestra un ejemplo de una función con ayuda basada en comentarios.
Cada sección de ayuda comienza con identificadores específicos como “.SINOPSIS”, “.DESCRIPCIÓN”, ”.PARÁMETRO«, y «.EJEMPLO”.
Function SayThisMessage {
<#
.SYNOPSIS
Displays a message on the screen with a color option.
.DESCRIPTION
Displays a message on the screen with a color option.
.NOTES
This function changes the console text color
and resets it to default after the message is displayed.
.PARAMETER Text
The message to display. Mandatory.
.PARAMETER Color
Optional text color.
.EXAMPLE
SayThisMessage `
-Text "Hello, I'm PowerShell. What can I do for you?"
Displays a message without changing the console text color.
.EXAMPLE
SayThisMessage `
-Text "Hello, I'm PowerShell. What can I do for you?" `
-Color 'Green'
Displays a message in green.
#>
param(
[Parameter(Mandatory)]
$Text,
[Parameter()]
$Color="Cyan"
)
if ($Color) {
$Host.UI.RawUI.ForegroundColor = $Color
}
$Text | Out-Default
[Console]::ResetColor()
}
Cuando importa esta función en PowerShell, puede mostrar su sistema de ayuda ejecutando los siguientes comandos.
Get-Help -Name SayThisMessage Get-Help -Name SayThisMessage -Examples Get-Help -Name SayThisMessage -Detailed Get-Help -Name SayThisMessage -Full Get-Help -Name SayThisMessage -Parameter <parameter name>
Conclusión
En conclusión, comentar su código de PowerShell es una práctica esencial que puede beneficiarlo enormemente a usted y a otras personas que puedan estar revisando o trabajando con su código. Comentar hace que su código sea más fácil de entender, mantener y modificar, especialmente cuando usted u otra persona vuelve a él después de que haya pasado un tiempo.
Si sigue las mejores prácticas que discutimos en esta publicación, como escribir comentarios claros y concisos y evitar comentarios innecesarios, puede asegurarse de que su código de PowerShell esté bien documentado y sea fácil de seguir.
Recuerde, comentar no solo es una señal de buenas prácticas de programación, sino que también muestra respeto por sus compañeros desarrolladores y ayuda a crear un entorno de codificación colaborativo y eficiente.
