FORMATTING

All code should be well formatted and easily readable according to the following guidelines:

• Code should be well commented for clarity throughout the script. If one is in doubt as to how obvious any section of code is, it should be commented. All functions should have comments explaining what is being accomplished (See Example 1).

EXAMPLE 1

////////////////////////////////////////////////////////////////////////////////
/// This script was written 2002/05/16 by
/// Scott Tiger, Systems Group.
/// scott.tiger@mcgill.ca
/// It requires global variables $Go_Connect and $Gs_Error to be 
/// passed before execution.
/////////////////////////////////////////////////////////////////////////////////

• An opening brace should be put on the same line as its preceding keyword, if possible; otherwise, line them up vertically.

EXAMPLE 2

while ($Condition){ // for short ones, align with keywords

	// do something;

}

• Do not put space before a semicolon.
• Surround most operators with space.
• Put blank lines between chunks of code that do different things.
• Do not put space between a function name instance and its opening parenthesis.
• Line up corresponding items vertically.
• Omit redundant punctuation as long as clarity doesn't suffer.

VARIABLE AND FUNCTION NAMING CONVENTIONS

All variable names should be self-descriptive with the possible exception of the simplest loop counters. Global variables start with 'G' with a lower case second letter to indicate the type of variable. Data types are 'i' - integer; 'f' - floating point or real number; 's' - string; 'd' - date etc.

• Constants and Global variables should be capitalized thus: < $Gi_CONSTANT > < $Gi_Variable >
• Local variables and functions should be capitalized thus: <?php $MyLocalVariable; ?> <?php function MyFunction(); ?> using initial caps and no underscores between words

Variables like $i or $j should only be used in very tight loops or as counters.

EXAMPLE 3

	for($i;$i<5; $i++){
		do something;
	}

REGULAR EXPRESSIONS

Regular expressions that are not trivial should be accompanied by comments explaining exactly what the author had intended.

EXAMPLE 4

$UserInput =~ '/[a-zA-Z]*[^<]/foo';  //replace with non-trivial expression
// Explain use of above expression

HTML

HTML tags should be lower case. Comments can be included where necessary.

EXAMPLE 5

<!—side menu table 
<table cellspacing='2' cellpading='2'>
  <tr>
    <td><a href="index.html">Go home</a></td>
  </tr>
</table>

CASCADING STYLE SHEETS

Cascading Style Sheets (CSS) are a simple way of adding style markup to web pages. Defined styles should be on one line if possible with the name of the selector and code in lower case letters. Longer definitions should be entered in a list format (See Example 8). Selectors should be ordered alphabetically at the top of the page or as an include file.

EXAMPLE 6

.commonheading { property1: value1; property2: value2 };

- or -

/* THIS STYLE IS USED TO DEFINE THE SIZE AND COLOR OF THE SIDE MENU */
.sidemenu{
    property1 : value1;
    property2 : value2;
	:
	:
    property10 : value10;
}

JAVASCRIPT

Should adhere to the same coding standards as PHP code. Functions that are common to several pages should be placed in an include file so that it will be stored in the client browser cache.

SQL STATEMENTS

SQL statements should be in upper case when used in php. Field names appear as they do in the database. SQL statements that are longer than one line should be right aligned on the SQL key words and aligned on variable statements.

EXAMPLE 7

$SqlStatement="SELECT * FROM J_TableName WHERE J_FieldName = 'Don%'";

- or -

$SqlStatement=	"SELECT	A.fname, A.lname, B.statusID "
	."FROM	names A, status B "
	."WHERE	B.statusID=23124"
	."OR	B.statusID=12311";

DATABASE FIELD NAMES

The database field names should represent both the data and the database from where it originates. It is important that we use the prefix to indicate the field's origin and the second portion to describe the field's contents. By using proper naming conventions the file structure will become self-documenting. That is, we will be able to figure out what is contained in the field by looking at the field name. The field name will be prefixed with a single uppercase letter database code followed by an underscore and an abbreviated field name no more than 13 characters long.

EXAMPLE 8

J_AbbrevFN

Database Codes

J - James
B - Banner
C - Charlotte