Documenting a Shell Script Post: 76646

Sponsored Content

Top Forums UNIX for Dummies Questions & Answers Documenting a Shell Script Post 76646 by jim mcnamara on Wednesday 29th of June 2005 01:49:09 PM

06-29-2005

Registered User

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.

jim mcnamara

View Public Profile for jim mcnamara

Find all posts by jim mcnamara

5 More Discussions You Might Find Interesting

1. UNIX for Dummies Questions & Answers

Any easy way of documenting cron entries?

I've been asked to do a high level summary of the cron jobs which run against a number of systems (to understand the potential scope for rewriting some of our core systems)...and was wondering how people have done this in the past. I've got approx 400 cron entries to go through. I will have...

2. Programming

Documenting code

I am programming using C++ and am wondering how to comment my project. For example, when I declare a class I created a header with some description, then have the declaration stage, which I don't comment. Then when I define the actual functions I will put details about it, what it does,...

3. Shell Programming and Scripting

Script Help -- documenting specific users that log into server

Hello All, I am trying trying to write a shell script that will do a couple things: 1.) Identify any username that logs into the server. 2.) When the user logs out, send them an email detailing their log in/out times, duration logged in, and what processes they ran. Basically,...

4. Shell Programming and Scripting

Documenting files with sed

All, I am looking for a way to improve this small one liner. one of the files has this kind of format public func <<<T>(array: , offset: Int) -> { return array.shiftedLeft(by: offset) } gsed -i '/public func/i /\/\/\public func \n/\/\==mark==public func' tresults in ///public func ...

5. Web Development

Documenting Installation Problem with vue-beautiful-chat

REF: https://github.com/mattmezza/vue-beautiful-chat $ git clone https://github.com/mattmezza/vue-beautiful-chat.git Cloning into 'vue-beautiful-chat'... remote: Enumerating objects: 534, done. remote: Total 534 (delta 0), reused 0 (delta 0), pack-reused 534 Receiving objects: 100%...

LEARN ABOUT DEBIAN

ucto

ucto(1) 						      General Commands Manual							   ucto(1)

NAME

       ucto - Unicode Tokenizer

SYNOPSYS

       ucto [[options]] [input-file] [[output-file]]

DESCRIPTION

       ucto ucto tokenizes text files: it separates words from punctuation, splits sentences (and optionally paragraphs), and finds paired quotes.
       Ucto is preconfigured with tokenisation rules for several languages.

OPTIONS

       -c configfile
	      read settings from a file

       -d value
	      set debug mode to 'value'

       -e value
	      set input encoding. (default UTF8)

       -f
	      disable filtering of special characters

       -L language
	       Automatically selects a configuration file by language code.  e.g. 'fr' will select the file  tokconfig-fr  from  the  installation
	      directory

       -l
	      Convert to all lowercase

       -u
	      Convert to all uppercase

       -n
	      Assume one sentence per line on input

       -m
	      Emit one sentence per line on output

       --passthru
	      Don't tokenize, but perform input decoding and simple token role detection

       -P
	      Disable Paragraph Detection

       -Q
	      Enable Quote Detection. (this is experimental and may lead to unexpected results)

       -S
	      Disable Sentence Detection

       -s <string>
	      Set End-of-sentence marker. (Default <utt>)

       -V
	      Show version information

       -v
	      set Verbose mode

       -x <DocId>
	      Output FoLiA XML, use the specified Document ID. (this disables usage of most other options: -nulPQvsS)

       -F
	      Read a FoLiA XML document, tokenize it, and output the modified doc. (this disables usage of most other options: -nulPQvsS)

BUGS

       likely

AUTHORS

       Maarten van Gompel proycon@anaproy.nl

       Ko van der Sloot Timbl@uvt.nl

								 2011 november 28							   ucto(1)