Scripting best practices

This article is excerpted from the new 4th edition of UNIX and Linux System Administration Handbook by Evi Nemeth, Garth Snyder, Trent R. Hein and Ben Whaley, published by Pearson/Prentice Hall Professional. Copyright 2011 all rights reserved.

There are whole books on best practices for coding, but here are a few basic guidelines:

• When run with inappropriate arguments, scripts should print a usage message and exit. For extra credit, implement --help this way, too.
• Validate inputs and sanity-check derived values. Before doing an rm -rf on a calculated path, for example, you might have the script double-check that the path conforms to the pattern you expect. You may find your scripting language's taint feature helpful.
• Return an appropriate exit code: zero for success and nonzero for failure. Don't feel compelled to give every failure mode a unique exit code, however; consider what callers will actually want to know.
• Use appropriate naming conventions for variables, scripts and routines. Conform to the conventions of the language, the rest of your site's code base and most importantly, the other variables and functions defined in the current project. Use mixed case or underscores to make long names readable. The naming of the scripts themselves is important, too. In this context, dashes are more common than underscores for simulating spaces, as in system-config-printer.
• Use variable names that reflect the values they store, but keep them short. number_of_lines_of_input is way too long; try n_lines.
• Consider developing a style guide so that you and your colleagues can write code according to the same conventions. A guide makes it easier for you to read other people's code and for them to read yours.
• Start every script with a comment block that tells what the script does and what parameters it takes. Include your name and the date. If the script requires nonstandard tools, libraries or modules to be installed on the system, list those as well.
• Comment at the level you yourself will find helpful when you return to the script after a month or two. Some useful points to comment on are the following: choices of algorithm, reasons for not doing things in a more obvious way, unusual paths through the code, anything that was a stumbling block during development. Don't clutter code with useless comments; assume intelligence and language proficiency on the part of the reader.
• Code comments work best at the granularity of blocks or functions. Comments that describe the function of a variable should appear with the variable's declaration or first use.
• It's OK to run scripts as root, but avoid making them setuid; it's tricky to make setuid scripts completely secure. Use sudo to implement appropriate access control policies instead.
• With bash, use -x to echo commands before they are executed and -n to check commands for syntax without executing them.
• Perl's -w option warns you about suspicious behaviors such as variables used before their values are set. You can include this option on a script's shebang line or turn it on in the program's text with use warnings.
• In Python, you are in debug mode unless you explicitly turn it off with a -0 argument on the command line. That means you can test the special __debug__ variable before printing diagnostic output.

Tom Christiansen suggests the following five Golden Rules for producing useful error messages:

• Error messages should go to STDERR, not STDOUT.
• Include the name of the program that's issuing the error.
• State what function or operation failed.
• If a system call fails, include the perror string ($! in Perl).
• Exit with some code other than 0.

Perl makes it easy to follow all five rules:

die "can't open $filename: $!";