UNIX for Dummies Questions & Answers

I've been working on a very long shell script that's becoming a mini-application. It is my first script, and continues to grow each week, becoming more and more complex.

I've been asked to document my script, beginning with basic information and then detailing any information about its functionality, in the event of my absence.

My question: Is there some kind of template I can take a look at for how to properly document one's script. I guess the same ideas can be applied for other programming languages, but I've never documented much of anything so I need to know how to effectively communicate the workings of my script to someone else who has no idea what it is.

Any and all suggestions welcome. Microsoft Word, or VI created "readme" file all welcome. (Do I use an outline? Is there an unofficial standard to how everyone else documents their code? Where do I begin?)

This is where coding, "art", and managers all bash heads.

For starters, I would create a header like this

Code:

# program name
# one sentence description - 
# argument 1  - what it is
# argument 2 .... thru argument n
# expected input/output - sample input -> output ( a few lines)
# maybe example suggested usage: myscript filename  > bigoutputfile

# ....................
# for each major block (like a big loop or a function) -- a one sentence description

If you are creating a giant script, consider creating functions for larger sections of your code. Put all of the functions at the top, with one-sentence desciptions for each one.

As you are finding out, it can be hard to debug a script, especially since you often end up with loads of variables. If you can, initialize all of the variables right at the top
and put a brief descirption of what it does:

Code:

let cnt=0      # loop control
let records=0 #record counter

Use meaningful names $REC_CNT, $SUM .. not $VAR or $X

There's a code analysis concept :Halstead volume - it relates the complexity of the vocabulary (number variable names, obfuscated names like $X) to the difficulty of maintaining code and making correct changes. The more variables, the greater the difficulty.