Programming Guidelines and Standards
by David Johnson <This email address is being protected from spambots. You need JavaScript enabled to view it.>

 

Let me begin by apologizing for even proposing any standards or guidelines. Very often these things cause an unnecessary burden for programmers and slow down 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 was having to invest to determine how to run and test each program was quite high, and that it would be good to have a consistent look and feel whenever possible. This will speed user acceptance and add to the usability of these tools and let us make enhancements and bug fixes at a faster rate. We hope that we are all intelligent enough to know when to throw the guidelines out the window and do some real work.

Naming Conventions

Type Extension Notes
Shell scripts .sh shell scripts regardless of the shell (Korn, Bourne, C, bash)
Awk scripts .awk awk scripts regardless of interpreter (awk, nawk, gawk)
C source .c C source files
C++ .cpp C++ source files
Perl .pl Perl scripts
HTML .html Hyper Text Markup Language
XML .xml eXtensible 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, programmer's name and any copyright information, and a brief description of what the program does.

# my_prog.sh
# 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

In an effort 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" ]
then
    ...setup NT variables...
else 
    ...setup Solaris variables...
fi

Path names

The standard distribution will normally go in the /opt/cassandra directory. In an effort 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 correctly execute if it can be run on both platforms.

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.

Perl
Anybody want to tackle this one?