Bloque de PowerShell Comentario | Guía para bloquear PowerShell Comentario

Introducción al comentario de PowerShell

Para cualquier programador, comentar el código es tan importante como la funcionalidad del código. Comentar es importante en la programación, ya que ayuda a los programadores a comprender el código y la funcionalidad desarrollados por otro programador. Escribir comentarios descriptivos y reveladores de PowerShell en scripts nos ayuda a los humanos a comprender el significado y el efecto del código y posiblemente explica los casos extremos que han surgido en el pasado. Este artículo cubrirá en detalle los diferentes tipos de comentarios, cuándo y dónde usarlos de manera efectiva en los scripts.

Sintaxis:

En PowerShell para comentar, se utiliza #. Todo lo que sigue a # en la misma línea se considera un comentario del intérprete de PowerShell. Esto se usa para comentarios de una sola línea, para comentarios de varias líneas o se usa un bloque de comentarios <#….#>.

Por ejemplo:

#example of single ling comment
Write-Host "The above line won't be printed"
<#
the below lines
won't be printed"
#>
Write-Host "above lines are example of multiline comment r script block"

Salida:

Comentar usando atajos:

Para comentar individualmente cada línea (#), seleccione una o más líneas y presione Ctrl + Q, o haga clic en Comentar (en la sección Editar de la pestaña Inicio). Resalte un bloque de código y presione Ctrl + Shift + Alt + Q, o seleccione Bloquear mensaje para agregar un bloque de comentarios. (PowerShell Studio versión 4.1.72 presenta el ícono Bloquear comentario). Para eliminar comentarios (en cualquier formato), seleccione las líneas que desea eliminar y presione Ctrl + Eliminar. Los comentarios se pueden eliminar usando Ctrl +shift+ Q o seleccione el bloque y seleccione descomentar en la ventana de opciones.

Agregar texto descriptivo para comentarios:

Cuando abre el script para ver qué hace, sería bueno que en su interior se enumeraran detalles útiles, como para qué sirve el script, quién lo creó y cuándo se creó. Un comentario de bloque en PowerShell es beneficioso para agregar texto descriptivo en sus scripts. De esta manera, el objetivo del script ya está dado y además es una excelente manera de incluir advertencias o cosas a tener en cuenta al utilizar el script.

Ejemplo:

<# This script will copy items from one site collection to another.
WARNING: Don’t run this in production using system account.
Last update: Feb 14, 2021
Last Updated By: Vignesh Krishnakumar
Last run time: 1 hour 30 mins
Duration: Run every month 15th
Inputs to be supplied: Source site, destination site
Output location: C:\output
#>

Creación de comentarios con fines de documentación:

A veces, el script debe ejecutarse de una forma u orden. No será conocido por una persona que no lo haya desarrollado. En ese caso, será útil documentar los pasos dentro de un bloque de script.

Ejemplo:

Entrada:

<#

Esta función obtiene credenciales de un archivo XML de forma cifrada para conectarse al sistema.

En caso de que el archivo XML no esté allí, haga lo siguiente.

1. Abra PowerShell como administrador
2. Ejecute este comando: 'Get-Credential | Export-CliXml .\test.XML'
3. Guarde el resultado en la misma carpeta que el script.
4. Una vez recibidas las credenciales, llame a la función principal
5. Una vez que se haya recibido el script se ejecuta correctamente, vaya y verifique los registros en la ruta de registro
6. En caso de cualquier error, copie la identificación y vaya y verifique en CRM

NOTA: Esto funcionará solo en la misma computadora
#>

Mejores prácticas para comentar

Nunca utilices el número de línea en los comentarios:

Al escribir código, es posible que se sienta tentado a incluir un número de línea en sus comentarios. Tendrás razón al pensar que agregar referencias de números de línea hace que tu código sea mucho más fácil de conocer. eso si estás seguro de que tu código nunca será modificado. Imagine que se inserta una línea de código de reemplazo en su secuencia de comandos. Esto puede significar que cada una de las referencias de números de carretera en sus comentarios ya se ha desplazado. Y para que la numeración de las carreteras sea precisa, deberá editar los comentarios para actualizarlos uno por uno.

No agregue comentarios al final de un guión:

Generalmente, un código se lee de arriba a abajo. Si el comentario que está agregando es vital para las siguientes líneas de código, entonces es lógico incluir los comentarios antes. Después de todo, si agrega comentarios dentro del script sobre el script, ¿no es más sensato tener los comentarios antes del código y no después?

Evitar comentarios al final de una línea:

Igual que el punto anterior, poner comentarios después del código, aunque esté en una línea equivalente, no es mejor que colocar el comentario debajo del código. Agregar comentarios en la parte superior del código puede causar errores de edición porque, en lugar de concentrarse en modificar el código, incluso tendría que tener en cuenta que el comentario avanza porque el código cambia.

Evite comentarios si no son necesarios:

A veces el código es demasiado simple y por lo tanto la intención ya es demasiado obvia y agregar un comentario allí es simplemente un desperdicio. Generalmente, durante esta situación, un comentario puede ser incluso más largo que el código al que hace referencia. Un comando obvio con un comentario. Si cree que el código se explica por sí mismo, querrá pensar en omitir agregar un comentario.

Ayuda basada en comentarios para funciones y scripts:

La asistencia basada en comentarios se escribe como una serie de comentarios. Todas las líneas dentro del bloque de comentarios se interpretan como comentarios. Todas las líneas durante un tema de ayuda basado en comentarios deben ser contiguas. Si un tema de ayuda basado en comentarios sigue a un comentario que no forma parte del tema de asistencia, debe haber al menos una línea en blanco entre la última línea de comentario que no es de ayuda y, por lo tanto, el comienzo de la ayuda basada en comentarios. Las palabras clave definen cada sección de ayuda basada en comentarios. Cada palabra clave de ayuda basada en comentarios está precedida por un punto. Las palabras clave pueden aparecer en cualquier orden. Los nombres de las palabras clave no distinguen entre mayúsculas y minúsculas. Por ejemplo, la palabra clave Descripción precede al esquema de una función o secuencia de comandos.

Conclusión

Así, el artículo explica en detalle sobre los comentarios o el bloqueo de comentarios en PowerShell. También explicó los diversos atajos disponibles y el uso de cada tipo de comentario. Para conocer más detalladamente es recomendable escribir guiones de muestra y practicarlos.

Artículos recomendados

Esta es una guía para bloquear comentarios en PowerShell. Aquí analizamos la introducción, la sintaxis y cómo funciona la función de filtro en Kotlin. con ejemplos. También puede consultar los siguientes artículos para obtener más información: