Liberum Help Desk, Copyright (C) 2000-2001 Doug Luxem
Liberum Help Desk comes with ABSOLUTELY NO WARRANTY
Please view the license.html file for the full GNU General Public License.
Filename: ProgrammingStyleGuide.txt
Date: $Date: 2001/10/13 19:03:38 $
Version: $Revision: 1.5 $
Purpose: This document explains the style guide to be used for all code in
the Liberum Help Desk project. All developers contributing code
should follow this guide.
SECTION I: GENERAL
1. FILE NAMES
- Files should all have a three letter extension as a guide to their contents.
- An exception would be HTML files for which the extension ".html" should be
used.
2. LINE LENGTHS
2.1. TEXT DOCUMENTATION FILES
- Plain text documentation files, eg this file, should be no wider than 80
chars so as to be viewable on a generic TTY interface.
2.2. ASP FILES
- ASP documents should be no wider than 110 characters wide, to allow for extra
long lines (SQL statements, etc), except where wrapping a line might cause
syntax errors or major readability issues.
2.3. HTML FILES
- HTML documents should be no wider than 110 characters wide, to allow for
extra long lines (SQL statements, etc), except where wrapping a line might
cause syntax errors or major readability issues.
3. INDENTATION
- All indentation should use two spaces.
- No hard tabs are to be used.
3.1. ASP & HTML FILES
- Programming lines should have two extra indent in addition to that of the
previous line. This will differentiate wrapped lines with regular indentation.
4. FILE HEADERS
- The header of each file should contain the following comments (see the top
of this file for an example):
1. The standard copyright header as shown at the top of this line.
2. The filename.
3. Last edit date - use the CVS Date variable.
4. The file version - use the CVS revision variable.
5. The file's purpose.
- In ASP files this should be an ASP comment rather than an HTML comment to
save end-user download time.
5. MISCELLANOUS
- Do not use the CVS Log keyword unless it would really be useful. It makes
for some really long files!
Section II: ASP
1. LANGUAGE
- All code should be written in VBScript.
2. COMMENTS
- All comments should use the standard Visual Basic / VBScript style within the
code itself, except for debugging purposes in which case use the standard HTML
comments.
- All comments should be before the line(s) they are relevent to, eg:
' See if user is authenticated
Call CheckUser(adoCon, sid)
- Comment should be at the same indent level as the code they refer to.
3. EMBEDDED HTML
- Use two double-quotes to display double-quotes in the output code.
Section III: HTML
1. LANGUAGE
- All HTML pages generated should conform to the official W3C XHTML 1.0
Transitional specification.
- All HTML pages generated should have the following three lines on the top of
each page:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
1.1. XHTML 1.0 COMPLIANCE GUIDELINES
- Use http://validator.w3c.org/ to validate output.
- All tags, attributes names and attribute values must be in lower case.
- All tags must have a closing tag or a " /" (a space and a forward slash)
placeholder, e.g.: <p>This is a paragraph.</p>, <img src="pic.gif" />, <hr />.
- All attribute values must be surrounded by double-quotation marks.
- All single-word attributes must be altered to a name-value pair, e.g.
<td nowrap></td> becomes <td nowrap="nowrap"></td>
- No font tags anywhere. Use the <div> or <span> tags with the relevant CSS
code instead.
- No center tags. Use <div align="center"></div> instead, or create a CSS
class.
2. ACCESSABILITY
- Generated pages should not have any level 1 errors on CAST Bobby.
- Generated pages should not have any glaring level 2 errors on CAST
Bobby.
- Level 3 errors and all warnings are optional, but some of them might be worth
following.
2.1. COMPLIANCE GUIDELINES
- Include a summary attribute on tables, eg <table summary="blah">. This
should explain the content of the table, even if the table is just used for
layout purposes.
- Include an apt description on all images.
- Do not use color to describe content.
- Do not use high-ASCII.
- Do not use non-alphanumberic characters for purposes for which they are not
designed.
3. MISCELLANEOUS
- There should be no space between the <a> tag and the first character of the
next word after it; likewise there should be no space between the </a> tag and
the last word before it.
SECTION IV: VARIABLE NAMING CONVENTIONS
1. GENERAL
- All variables should use descriptive names.
- Variables need to have a 2-4 letter prefix in lowercase that describes the
data type used.
- Variables should be lower case, except for capitalizing the start of each
word. An example would be "strFullName" or "intRecordCount".
2. VARIABLE DECLARATION
- All variables must be declared at the start of the page or procedure where
they are being used.
- "Option Explicit" must be declared at the start of every ASP page.
3. SESSION AND APPLICATION VARIABLES
- Avoid using Application variables. All application-wide settings should be
held in the database.
- Session variables should be used minimally. User state should be held in
the database and other data should be made part of query strings or form
fields.
- All Session and Application variables must start with the prefix "lhd_" to
avoid conflicts with other IIS applications.
4. PREFIXES
- All variables should start with prefixes outlined in the table below.
Data Type : Prefix : Example
---------------------------------
Boolean : bln : blnEnable
Character : chr : chrInitial
Date/Time : dtm : dtmStartDate
Double : dbl : dblDistance
Error : err : errSyntax
Integer : int : intCounter
Long : lng : lngLength
Memo/Text : txt : txtDescription
Object : obj : objMessage
String : str : strFirstName
Variant : var : varUserList
ADO Record Set : rst : rstQueryResults
ADO Connection : cnn : connADOConnection
