Programming Guidelines and Standards

by David Johnson

Let me begin by apologizing for even proposing any standards or guidelines. These things often cause an unnecessary burden for programmers and slow development efforts. With that being said, when I started bringing together the programs sent to me by the many talented people out there, I found the amount of time I had to invest in determining how to run and test each program was relatively high and that it would be good to have a consistent look and feel whenever possible. This will speed up user acceptance, add to these tools’ usability, and let us make enhancements and bug fixes faster. We hope we are all intelligent enough to know when to throw the guidelines out the window and do some real work.

Naming Conventions

Shell scripts.shshell scripts regardless of the shell (Korn, Bourne, C, bash)
Awk scripts.awkawk scripts regardless of interpreter (awk, nawk, gawk)
C source.cC source files
C++.cppC++ source files
Perl.plPerl scripts
HTML.htmlHyper Text Markup Language
XML.xmleXtensible Markup Language

Shell scripting

The first line in any shell script should identify which shell interpreter to use.

 #!/bin/sh      Bourne shell 
 #!/bin/ksh     Korn shell
 #!/bin/csh     C shell

The second line should be a blank comment.

The next few lines should have the program name, the programmer’s name and any copyright information, and a brief description of what the program does.

 # David Johnson ©2000 under GNU copyleft license
 # This script fixes every problem known to man, except the
 # one you have. It works best on Monday mornings while you
 # are sleeping.

(Here’s a sample text block about the GNU license and disclaimer that you can cut and paste directly into your script file.)

Here begins the body of the script.

OS check

To make scripts as generic as possible, let’s check to see if we are on NT or Solaris and take appropriate action.

 if [ "`uname`" = "Windows_NT" ]
    ...setup NT variables...
    ...setup Solaris variables...

Path names

The standard distribution will typically go in the /opt/cassandra directory. To allow maximum flexibility with minimal headache, we should check to see if the variable CASSANDRA_HOME exists. If not, set CASSANDRA_HOME to be /opt/cassandra.

Temporary files should go in $CASSANDRA_HOME/tmp.

Unusual command problems under NT

If the script uses a command that also exists in the windows path, i.e., sort, find, etc., then the script will need an explicit path to execute if it can be run on both platforms correctly.

 if [ $on_NT –eq "1" ] d:/nutc/mksnt/sort –u $file
 if [ $on_SOLARIS –eq "1"] sort –u $file

That’s all I have for now on shell scripts, but I am open to suggestions for more, better, or fewer standards.

Other Scripts

awk Scripting
I was kind of hoping Winston would handle this one.

C programs
Looking for some input here. I use the gnu C compiler.

C++ programs
Looking for some input here. I use the gnu C++ compiler.

Does anybody want to tackle this one?

Scroll to Top