Sysadmin University: Cómo documentar código y scripts en Linux

¿Alguien te ha pedido o te ha pedido que documentes tu código? Si no lo has hecho, entonces eres realmente raro. Es una lucha constante para los administradores y desarrolladores de sistemas documentar adecuadamente su código y scripts. Todo el mundo, al parecer, quiere que lo hagas, pero nadie te muestra cómo hacerlo. Este artículo muestra cómo documentar su código y scripts.

La documentación puede ser tediosa, aburrida y menos que gratificante cuando te das cuenta de que una audiencia muy limitada leerá o hará referencia a tu comentario incrustado. Es posible que solo usted y otra persona puedan ver sus joyas literarias, pero ese no es realmente el punto. El punto es que incluso usted, como programador, probablemente necesite consultar esta documentación en el futuro. Deberá recordar cuál era el propósito de un fragmento de código en particular, o puede necesitar saber cómo reproducir un bucle especial para otro proyecto. Dentro de seis meses no recordará la lógica o el propósito detrás de cada pieza de código.

La documentación corrige esto.

No hay reglas específicas para documentar el código, pero hay algunas pautas útiles que lo harán muy feliz a usted o a un compañero de trabajo. En script o código de programa, la documentación se denomina "comentarios". Me refiero a la documentación ya los comentarios indistintamente. Para este artículo estoy usando el # símbolo para identificar una línea de texto comentada, ya que este es el estándar para los scripts de shell de Linux. Otros idiomas tienen sus propios símbolos para identificar los comentarios.

Recuerde que la primera línea de un script de shell parece un comentario, pero no lo es. La línea shebang define el shell en el que se ejecutará el script. #!/bin/bash, por ejemplo.

Debajo de la línea shebang, puede comenzar su documentación. Comience con la fecha de creación, el nombre del autor y el propósito general del guión o el problema que resuelve.

#!/bin/bash

# Date: 07/22/2020
# Author: Ken Hess
# This script parses the access log, strips out IP addresses that don't match the 192.168.1.0/24 pattern, and enters them
# into the /etc/hosts.deny file.

Ahí tienes la función del script, quién lo creó y cuándo fue creado. El siguiente paso es proporcionar instrucciones de uso y determinar si la secuencia de comandos requiere argumentos, cambios u otra entrada.

# Usage: $ ./documentation.sh

La siguiente parte es la documentación de los fragmentos de código del script. Debe documentar cada paso por separado. Los comentarios siempre preceden al código que documentan.

# Parse the access log and extract IP addresses that don't match 192.168.1.0/24.
<code to read the access log and extract IP addresses>

# Write the IP addresses to a file (/tmp/addresses.txt)
<code to write output to a file>

# Read each line from /tmp/addresses.txt and enter them into /etc/hosts.deny
<code to read /tmp/addresses.txt and enter them into /etc/hosts.deny>

# Remove /tmp/addresses.txt
<code to remove /tmp/addresses.txt)

Para revisar este script posteriormente, agregue el autor si es diferente al original, la fecha de modificación y el código modificado con la fecha correspondiente.

# Modified: 07/29/2020 
# Modified by: Tyler Carrigan

# 07/29/2020 - Modified to add a check for IP addresses in /etc/hosts.allow prior to adding them to the /etc/hosts.deny file.
<code to compare /etc/hosts.allow with /tmp/addresses.txt)

# 07/29/2020 - Modified to remove addresses from /tmp/addresses.txt that match in /etc/hosts.allow so that they don't get denied access.
<code to remove addresses that match /etc/hosts.allow and rewrite /tmp/addresses.txt>

Ahora que ha visto todas las partes, así es como se ve el guión, todo ensamblado y en el orden correcto.

#!/bin/bash

# Date: 07/22/2020
# Author: Ken Hess
# This script parses the access log, strips out IP addresses that don't match the 192.168.1.0/24 pattern, and enters them
# into the /etc/hosts.deny file.

# Modified: 07/29/2020 
# Modified by: Tyler Carrigan
# Modified to prevent IP addresses in /etc/hosts.allow from being duplicated in /etc/hosts.deny.

# Usage: $ ./documentation.sh

# Parse the access log and extract IP addresses that don't match 192.168.1.0/24.
<code to read the access log and extract IP addresses>

# Write the IP addresses to a file (/tmp/addresses.txt)
<code to write output to a file>

# 07/29/2020 - Modified to add a check for IP addresses in /etc/hosts.allow prior to adding them to the /etc/hosts.deny file.
<code to compare /etc/hosts.allow with /tmp/addresses.txt)

# 07/29/2020 - Modified to remove addresses from /tmp/addresses.txt that match in /etc/hosts.allow so that they don't get denied access.
<code to remove addresses that match /etc/hosts.allow and rewrite /tmp/addresses.txt>

# Read each line from /tmp/addresses.txt and enter them into /etc/hosts.deny
<code to read /tmp/addresses.txt and enter them into /etc/hosts.deny>

# Remove /tmp/addresses.txt
<code to remove /tmp/addresses.txt)

Recuerde que los scripts, el código y la documentación son entidades modificables y deben mantenerse y actualizarse según sea necesario. Como puede ver en este ejemplo, el segundo autor hizo un cambio grande y muy necesario. El guión solía funcionar, pero los cambios lo han mejorado. Los cambios se habrían visto como invasivos si el segundo autor no los hubiera notado.

La documentación es necesaria y vale la pena el tiempo y el esfuerzo involucrados. Y no importa cuán buena sea tu memoria, en unos meses o un año no recordarás la intención o el razonamiento detrás de algunos de los guiones que creas. Documento. Documento. Documento.

Artículos de interés

Subir