¿Cómo comentar el código de PowerShell? – TrucosInformaticos

Powershell

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.

powershell ise comentario

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.

comentar en powershell ise

O varias líneas.

bloque de comentarios de powershell

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.

atajo de comentario de powershell ise

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.

comentario de bloque powershell ise

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.

atajo de comentario de PowerShell

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>

comentario de powershell

como comentar en powershell ise

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.

5/5 - (213 votos)

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *