Documentación y comentarios
Los comentarios que contradicen el código son peores que no tener comentarios. Siempre es prioritario mantener los comentarios actualizados cuando el código cambia!
Los comentarios deben estar en inglés, y deben ser frases completas. Si el comentario es corto, se puede omitir el punto al final.
Recuerde que los comentarios deben servir para su razonamiento y toma de decisiones, no para intentar explicar lo que hace un comando. Con la excepción de las expresiones regulares, PowerShell bien escrito puede ser bastante auto-explicativo.
# Do not write:# Increment Margin by 2$Margin = $Margin + 2# Maybe write:# The rendering box obscures a couple of pixels.$Margin = $Margin + 2
No te pases con los comentarios. A no ser que tu código sea especialmente oscuro, no precedas cada línea con un comentario: hacerlo rompe el código y lo hace más difícil de leer. En su lugar, escriba un único comentario de bloque.
Los comentarios de bloque generalmente se aplican a parte o a todo el código que les sigue, y están sangrados al mismo nivel que ese código. Cada línea debe comenzar con un # y un solo espacio.
Si el bloque es particularmente largo (como en el caso del texto de documentación) se recomienda utilizar la sintaxis de comentario de bloque <# ... #>, pero debe colocar los caracteres del comentario en sus propias líneas, y sangrar el comentario:
# Requiring a space makes things legible and prevents confusion.# Writing comments one-per line makes them stand out more in the console.<#.SYNOPSISReally long comment blocks are tedious to keep commented in single-line mode..DESCRIPTIONParticularly when the comment must be frequently edited,as with the help and documentation for a function or script.#>
Los comentarios en la misma línea que un enunciado pueden distraer, pero cuando no afirman lo obvio, y particularmente cuando tienes varias líneas cortas de código que necesitan explicación, pueden ser útiles.
Deberían estar separados del enunciado del código por al menos dos espacios, e idealmente, deberían alinearse con cualquier otro comentario en línea en el mismo bloque de código.
$Options = @{Margin = 2 # The rendering box obscures a couple of pixels.Padding = 2 # We need space between the border and the text.FontSize = 24 # Keep this above 16 so it's readable in presentations.}
La ayuda basada en comentarios debe estar escrita en un lenguaje sencillo.
No estás escribiendo una tesis para tu clase de Escritura Técnica de la universidad – estás escribiendo algo que describe cómo funciona una función. Evita las palabras innecesariamente grandes y mantén tus explicaciones cortas. No estás tratando de impresionar a nadie, y las únicas personas que leerán esto están tratando de averiguar cómo usar la función.
Si estás escribiendo en lo que es, para ti, un idioma extranjero, las palabras más simples y las estructuras de las oraciones más simples son mejores, y es más probable que tengan sentido para un lector nativo.
Sea completo, pero sea conciso.
Ubicación
Para asegurar que la documentación se queda con la función, los comentarios de la documentación deben colocarse DENTRO de la función, en lugar de encima. Para que sea más difícil olvidarse de actualizarlos cuando se cambia una función, debe mantenerlos en la parte superior de la función, en lugar de en la parte inferior.
Por supuesto, eso no quiere decir que ponerlos en otro lugar esté mal – pero esto es más fácil de hacer, y más difícil de olvidar de actualizar.
Ponga los detalles en las Notas
Si desea proporcionar explicaciones detalladas sobre el funcionamiento de su herramienta, utilice la sección Notes para ello.
Describa la función
Cada comando de función de script debe tener al menos una breve declaración que describa su función. Esto es el Synopsis.
Documentar cada parámetro
Cada parámetro debe ser documentado. Para que sea más fácil mantener los comentarios sincronizados con los cambios en los parámetros, la ubicación preferida para los comentarios de documentación de los parámetros es dentro del bloque param, directamente encima de cada parámetro. Se pueden encontrar ejemplos en los fragmentos de ISE:
param (# Param1 help description$Param1,# Param2 help description$Param2)
También es posible escribir .PARAMETER declaraciones con el resto de los comentarios de documentación, pero la experiencia demuestra que es más probable que se mantengan actualizados si los pone más cerca del código que documentan.
Proporcione ejemplos de uso
Su ayuda debería proporcionar siempre un ejemplo para cada caso de uso importante. Un «ejemplo de uso» no es más que un ejemplo de lo que usted escribiría en Powershell para ejecutar el script – incluso puede cortar y pegar uno desde la línea de comandos mientras está probando su función.
function Test-Help {<#.SYNOPSISAn example function to display how help should be written..EXAMPLEGet-Help -Name Test-HelpThis shows the help for the example function.#>param (# This parameter doesn't do anything.# Aliases: MP$MandatoryParameter)<# code here ... #>}
DOC-01 Escriba ayuda basada en comentarios
Siempre debe escribir ayuda basada en comentarios en sus scripts y funciones.
La ayuda basada en comentarios tiene el siguiente formato:
function Get-Example {<#.SYNOPSISA brief description of the function or script..DESCRIPTIONA longer description..PARAMETER FirstParameterDescription of each of the parameters.Note:To make it easier to keep the comments synchronized with changes to the parameters,the preferred location for parameter documentation comments is not here,but within the param block, directly above each parameter..PARAMETER SecondParameterDescription of each of the parameters..INPUTSDescription of objects that can be piped to the script..OUTPUTSDescription of objects that are output by the script..EXAMPLEExample of how to run the script..LINKLinks to further documentation..NOTESDetail on what the script does, if this is needed.#>