Sysadmin university: How to document code and scripts in Linux

Have you had someone ask or tell you to document your code? If you haven't, then you are rare, indeed. It's a constant struggle to get sysadmins and developers to document their code and scripts properly. Everyone, it seems, wants you to do it, but no one shows you how. This article demonstrates how to document your code and scripts.

Documentation can be tedious, annoying, and less than gratifying when you realize that a very limited audience will ever read or refer to your embedded commentary. It's possible that only you and one other person might ever see your literary gems, but that isn't really the point. The point is that even you, as the programmer, will probably need to refer to this documentation in the future. You will need to recall what a particular code snippet's purpose was, or you might need to know how to reproduce a special loop for another project. You won't remember six months from now what the logic or the purpose was behind each bit of code.

Documentation fixes that.

There are no specific rules for documenting code, but there are some helpful guidelines that will make future you or a colleague very happy. In a script or program code, documentation is referred to as "comments." I refer to documentation and comments interchangeably. For this article, I use the # symbol to identify a line of commented text because it is the standard for Linux shell scripts. Other languages have their own symbols to identify comments.

Remember that the first line of a shell script looks like a comment, but it isn't. It's the shebang line that defines the shell in which the script will run. #!/bin/bash, for example.

Under the shebang line, you can begin your documentation. Begin with the creation date, author's name, and the script's overall purpose or problem it solves.

#!/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.

There you have the function of the script, who created it, and when it was created. The next step is to supply usage instructions and whether the script requires any arguments, switches, or other input.

# Usage: $ ./documentation.sh

The next part is the documentation for the script's code snippets. You have to document each step separately. Comments always precede the code they document.

# 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)

To revise this script later, add the author if different from the original, the modification date, and the modified code with the corresponding date.

# 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>

Now that you've seen all of the parts, here's what the script looks like all put together and in the correct order.

#!/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)

Remember that scripts, code, and documentation are editable entities, and they have to be maintained and updated as needs require. As you can see from this example, the second author made a significant and much-needed change. The script worked before, but the changes made it better. The changes would have been perceived as invasive had the second author not made a note of the modifications.

Documentation is necessary and worth the time and effort to do. And no matter how great your memory is, in a few months or a year from now, you won't remember the intent or the reasoning behind some of the scripts you create. Document. Document. Document.

[ Download now: A sysadmin's guide to Bash scripting. ]