Using The Common Gateway Interface: CGI Coding Guidelines

This document is meant to describe, in some detail, a general style for scripts to be run on the WPI web servers. Most of what we describe will be applicable to scripts written in Perl. CGI's written in other languages will be acceptable, as long as they fall within the guildelines applicable to those languages. We do, however, prefer Perl. WPI does not support Active Server Pages or FrontPage Server Extentions, and have no intention to do so in the forseeable future. If you want to write a script in other languages, please check with the Webmaster first. In no cases will we install a binary CGI without first reviewing the source and compiling it ourselves.

Much of what is written below is based on the article, In Defense of Coding Standards.

General Concepts

WPI's system administrators and developers tend to lean toward the style of script that includes the form and the script to handle the form in a single file. we find this makes it much easier to figure out what form calls which script, and it allows for easier error-checking and requires less hitting the back button or re-entering data if the user is required to recheck their input.

This does require a bit more work at the start than simply having a plain HTML file and a separate file with the script, but it does make up for it in the long run. Also, commonly-used procedures can be kept in a library for easy reuse. we will be making available a library of reusable code chunks and subroutines to make this easier.

Also, WPI requires that scripts standardize around one of two cgi libraries, either CGI.pm or cgi-lib.pl (both of which are available on WPI's servers). Writing your own custom cgi-variable parsing library for each script, or cutting and pasting a block of code from one script to another is a waste of time and only causes problems later. (Imagine finding a subtle bug after writing four or five complete scripts using that code and then having to remember which scripts use that chunk of code and go back and change them all.)

Files pertaining to a single script or set of scripts that make up an application should be placed in their own directory. Please do not hard-code any paths into your scripts. If you have paths that will be referenced anywhere in your scripts, create an include file and use a global variable for those paths. The advantages of this should be obvious.

Similarly, if you have passwords, server names, usernames, or anything else that may change throughout the course of the lifetime of an application, pull those out and make them into global variables. The mysql server, for example, may move, or we may switch to msql or Oracle or something – that server-type variable that gets used every time you open a new database handle in your DBI calls should be set up so you only have to change it once.

This does end up requiring a lot of extraneous files. This is why we want to have all the files specific to a single application in their own directory. Again, we want to be able to move and rearrange applications with a minimum of trouble. we also want to get as much as we can out of the cgi-bin directory itself and into subdirectories.

Guidelines

The verbosity of all names should be proportional to the scope of their use
The plurality of a variable name should reflect the plurality of the data it contains. In Perl, $name is a single name, while @names is an array of names.
In general, follow the language's conventions in variable naming and other things. If the language uses variable_names_like_this, you should too. If it uses ThisKindOfName, follow that.
Failing that, use UPPER_CASE for globals, StudlyCaps for classes, and lower_case for most other things. Note the distinction between words by using either underscores or StudlyCaps.
Function or subroutine names should be verbs or verb clauses. It is unnecessary to start a function name with do_.
Filenames should contain underscores between words, except where they are executables in $PATH. Filenames should be all lower case, except for class files which may be in StudlyCaps if the language's common usage dictates it.
Name Perl scripts with a .pl extension, and CGI scripts with a .cgi extension. One exception: Perl scripts in $PATH may omit the .pl.
Don't cut-and-paste chunks of code. If you find yourself doing this, make it a subroutine.
Don't use a whole lot of independant variables for a group of related variables (for example, the inputs to a CGI) when an array or hash will do.
Use functions from common libraries whenever possible. Don't rewrite things that have already been written.
Use taint checking! Security is a good thing.

Maintained by webmaster@wpi.edu
Last modified: Jun 10, 2004, 11:37 EDT