Cómo comentar en Bash

Introducción

Los comentarios en bash scripting y la programación en general ayudan a que un programa sea más fácil de entender. Cuando se ejecuta un programa, el intérprete ignora las líneas comentadas. Sin embargo, los comentarios ayudan con la legibilidad general del programa.

Al mirar el código más adelante, es útil tener explicaciones descriptivas y valiosas sobre lo que hace el código. Comentar el código para su uso posterior es una práctica común y es una parte esencial de la programación y las secuencias de comandos bash.

Este tutorial demuestra cómo usar los comentarios y las mejores prácticas de comentarios en scripts bash.

Requisitos previos

• Un sistema que ejecuta Linux.
• Acceso a la línea de comando/terminal.
• Un editor de texto, como Vi/Vim.

Cómo comentar en Bash

Al escribir secuencias de comandos bash, cualquier texto después de un signo de hash (# ) indica el comienzo de un comentario y cualquier texto después de # en la misma línea no se ejecuta.

Cuando se usa un editor de texto o IDE, los comentarios se colorean de manera diferente al resto del código. Son fáciles de notar y buscar en códigos más extensos.

La única excepción es el shebang (#! ), que suele estar en la primera línea del script. El shebang le dice al sistema operativo qué intérprete usar para el código.

Los comentarios en línea después del shebang dan como resultado "No existe tal archivo o directorio " error.

Comentario Bash de una sola línea y en línea

Tanto los comentarios de una sola línea como en línea en los scripts de bash comienzan con el signo de almohadilla (# ):

# This is a comment

El espacio adicional después del letrero no es necesario. Sin embargo, ayuda con la legibilidad.

Siga el ejemplo a continuación para crear un script con comentarios:

1. Abra la terminal (CTRL +ALT +T ) y crea un script usando Vi:

vi comment.sh

2. Agrega el siguiente código:

# A comment is considered a single line if you do not press Enter. Below is the shebang, indicating the script uses the bash shell.
#!/bin/bash
# This is a single line comment above a command.
echo "Hello world!" # This is an inline comment.
# This is a single line comment below a command.

El guión incluye las siguientes líneas:

• Línea 1 es un comentario de Bash de una sola línea. Visualmente, la declaración ocupa dos líneas.
• Línea 2 es el shebang. El script se ejecuta usando el intérprete de shell Bash, ubicado en /bin/bash .
• Líneas 3 y 5 también son comentarios de una sola línea antes y después de un comando, respectivamente.
• Línea 4 es un comando de eco simple con un comentario en línea.

3. Guarde y cierre Vi:

:wq

4. Cambie los permisos del script a ejecutable:

chmod +x comment.sh

5. Por último, ejecute el script con:

./comment.sh

Los comentarios no se muestran al ejecutar el script .

Comentario multilínea y Block Bash

Para crear comentarios bash de varias líneas, comience cada línea con el signo de almohadilla (# ):

# This is the first line
# This is the second line

Otra forma poco convencional de crear comentarios de bloque multilínea es usar el comando bash null (: ) junto con la notación heredoc:

: << 'COMMENT'
This is the first line
This is the second line
COMMENT

Fundamentalmente, bash no admite comentarios en bloque. Este método funciona como un truco si un comentario de bloque es esencial para un caso específico.

Pruebe el siguiente ejemplo para ver cómo funcionan los comentarios multilínea y de bloque en scripts de bash:

1. Abra la terminal (CTRL +ALT +T ) y cree un script de shell usando Vi:

vi multiline.sh

2. Copia y pega el siguiente código:

: << 'COMMENT'
This is a multiline block comment
using the single quote heredoc
and bash null command.
COMMENT
echo "Hello world!"
# This is a multiline comment
# using the single line notation.

El código hace lo siguiente:

• Líneas 1 y 5 son los delimitadores heredoc.
• Líneas 2-4 son los contenidos de los comentarios del bloque.
• Línea 6 es el echo comando.
• Líneas 7 y 8 son varios comentarios de una sola línea, que actúan como comentarios de varias líneas.

3. Guarde el archivo y cierre Vi:

:wq

4. Cambie los permisos del script a ejecutable:

chmod +x multiline.sh

5. Finalmente, ejecute el script para ver el resultado:

./multiline.sh

La salida del terminal muestra solo el resultado en el echo comando, mientras que las líneas comentadas no se muestran.

Prácticas recomendadas y consejos para los comentarios de Bash

Aunque no hay reglas específicas para comentar en bash, ciertas prácticas son útiles cuando se usan comentarios. Estas prácticas y consejos pretenden ayudarlo a aprovechar al máximo los comentarios en bash.

1. Incluir un encabezado de archivo

Todos los scripts que no son tan evidentes a primera vista deben incluir un encabezado de archivo. El encabezado tiene varios propósitos:

• Explica lo que hace el código de un vistazo.
• Indica la autoría.
• Explica el aviso de licencia y proporciona la declaración de permiso para el código protegido por derechos de autor.

Use comentarios al comienzo de un código para explicar estos puntos. Además, si un código es parte de un proyecto, incluya el nombre del proyecto.

2. Evite los comentarios de bloque no convencionales

Aunque los comentarios en bloque son posibles en los scripts de bash, es un mal hábito usarlos. El código no se nota tan fácilmente como un comentario normal porque los editores de texto no los representan como comentarios. Además, la búsqueda es mucho más fácil cuando hay una sintaxis de comentarios unificada.

3. Evite comentarios largos e innecesarios

Mantenga los comentarios lo más cortos posible y al grano. La verbosidad es innecesaria y hace que el código sea más difícil de leer.

Del mismo modo, solo comente el código que sea difícil de entender. Un comentario sobre un simple echo El comando es innecesario, mientras que el código que usa una declaración de expresiones regulares compleja requiere una indicación rápida de lo que hace.

4. Comentarios y Funciones

Todas las funciones bash se benefician de los comentarios que explican el propósito, las entradas esperadas y las salidas. La excepción son las piezas cortas de código que son evidentes.

Indique lo siguiente para cada función:

• Breve descripción de la operación.
• Una lista de variables globales o modificadas.
• Los argumentos de entrada esperados.
• Lo que el proceso envía a la terminal.
• Los valores de retorno esperados.

A continuación se muestra un ejemplo de una función que documenta cada uno de los puntos anteriores:

PREFIX="Hello "
#### FUNCTION BEGIN
# Prints a greeting
# GLOBALS: 
# 	PREFIX
# ARGUMENTS: 
# 	Name as a String to use for greeting
# OUTPUTS: 
# 	Writes String to STDOUT
# RETURN: 
# 	0 if success, non-zero otherwise.
### FUNCTION END
function () {
	echo "${PREFIX}: $1!"
}

Ajuste el ejemplo a su caso de uso.

5. Etiquete consistentemente

Use comentarios para etiquetar el código que necesita mejoras, implementación o modificación. Cree una etiqueta de comentario consistente para una tarea diferente para que sea más fácil buscar en los comentarios.

Por ejemplo, comience y finalice la explicación de cada función con # FUNCTION BEGIN o agrega # TODO comentarios para futuras tareas. Del mismo modo, decida las etiquetas que le parezcan adecuadas y mantenga la coherencia en todo el código.