Coding Standards and Practices

Introduction

One of the most important aspects of coding websites for use within the Dark Brotherhood is the ability of future generations of members to be able to successfully use and modify the code to fit their needs. Unfortunately, many [coders do not leave clean and well-documented code, leaving it nearly impossible to navigate what is left behind. As a part of the effort to continuously improve the code used by the Brotherhood, this document has been developed. This document outlines the best practices and naming conventions that are to be used in all Dark Jedi Brotherhood websites.

The purpose of this document is to assist beginning and experienced developers in the creation of efficient pages. While a wealth of information can be found on the Internet, many tips and code samples simply attempt to answer a question or solve a task at hand. A developer must take that information and determine not only how the answer works on the site, but also take into consideration how a technique scale with the rest of the project. By reviewing the best practices mentioned in this document, applications can be made more efficient. It should be noted that this document makes generalizations. Certain practices may need to be ignored depending on the specific needs of a website.

Files

RULE: Do not place ASP code or any other type of server side code in any files other then .asp files.

RATIONAL: Placing ASP code in files that are not .asp will allow regular users to use a web browser to view the source of the code. ASP code in a .html page, for example can be viewed by anyone, potentially giving away sensitive information or passwords.

RULE: Any pages that do not use server side code of some sort should use the .html extension

RATIONAL: Many sites use custom page extensions that are not .html. This causes problems in some browsers. For consistency and maximum compatibility, .html should be used throughout.

RULE: Use prefixes for filenames of pages with similar functions. For Example: All the pages dealing with user would be userUpdate.asp, userDisplay.asp.

RATIONAL: Consistent use of descriptive prefixes assists in file management and ease of access to needed files.

RULE: Use descriptive filenames. For example: Do Not use a-acc4.asp. Do use a-accApproveCharacterSheet.asp

RATIONAL: Descriptive file names help with productive file management and each of access to needed files.

Variable Declaration, Naming and Type Notation

RULE: Each variable should be dimmed and initialized at the start of the appropriate code section. “Option Explicit” should be declared at the very start of each .asp file. Variables should be commented to display their use.

RATIONAL: Using Option Explicit forces the coder to dim variables before they are used. Dimming variables and initializing them to the proper values speeds up the processing of the page.

RULE: Use the Hungarian notation for naming variables and objects.

RATIONAL: The purpose of the Hungarian notation is to be able to interpret the type and purpose of a variable without having to search through the code for its use.

EXAMPLES:

Type	Prefix	Example
String	str	strName
Integer	Int	intUserId
Double, Float	dbl	dblDollarValue
Boolean	bln	blnIsBlank
Recordset	rs	rsMembers

RULE: Use the Hungarian notation for form fields to make forms clearer

RATIONAL: The purpose of the Hungarian notation is to be able to interpret the type and purpose of a field without having to search through the code for its use.

EXAMPLES:

Form Component	Prefix
Input Box	txtUserName
Check Box	chkOrder
Button	btnSubmit
Hidden Field	hdnUserId

RULE: Use all uppercase when declaring a const variable

RATIONAL: Using all uppercase letters for constants helps to clearly indicate which variables are constants without referring to the declaration

EXAMPLE: Const MIN_USERS = 3

RULE: Variable names should be meaningful and descriptive.

RATIONAL: Combined with the Hungarian notation, this leads to clear code, where the purpose and type of each variable is obvious from inspection.

EXAMPLES:

Good	Bad
strUserName	N
intUserId	uid

Code Documentation

RULE: Include a File Information section at the very top of you page, include File Author, Date Created, Description and Date / Description of any changes made to the code.

RATIONAL: Documenting changes, the authors name and the date of the creation allow for easy understanding of and access to the author in the future.

RULE: Document all variables.

RULE: Document all conditional statements, explain what it is checking.

RULE: Document all functions, explaining what the function does and what it is returning.

RULE: Document all tricky and unusual code.

Code Structure and Practices

RULE: Avoid context switching such as switching between ASP and HTML or switching between VBscript and Jscript on the same page. Try to perform all server side code at the top of your page before executing any HTML code.

RATIONAL': Switching between ASP and HTML causes a slow down in script processing time and leads to sloppy code. Forcing the ASP code at the top of the page requires planning and forethought from the coder.

RULE: Combine multiple "Response.Write" lines into one larger single statement whenever possible

RATIONAL: Speeds up script processing times. Leads to cleaner code

RULE: Use arrays rather than dictionary objects or collections.

RATIONAL: Arrays are always faster and more efficient than other storage methods and use less memory than dictionary objects or collections.

RULE: Indent blocks of code with an indent size of four (4) spaces

RATIONAL: Indents allow for easier readability of code. Four spaces is an industry-standard indent.

RULE: Use white space to separate those blocks.

RATIONAL: White space allows for easier readability of code

RULE: Put all file includes below the File Information comment block.

RATIONAL: Having includes at the top of the page instantly allows the coder to see what the file is referencing and follows the dichotomy calling for ASP to be at the top of the page.

RULE: Declare all global variables below the file includes.

RATIONAL: Global variables should be declared at the top of the file to increase ease of use and notice of what they are

RULE: Put the ASP delimiters <% %> on the left hand margin.

RATIONAL: Allows for easier readability of code. Makes it easier to distinguish code blocks.

RULE: Use all lowercase when writing HTML tags

RATIONAL: Allows for easier readability of code, lowers confusion with Database calls and Constant declarations.

RULE: Use “Sub” rather than “Function” for functions that have no return value

RATIONAL: Subs are built to be used without returning a value. Using them in the place of functions increases code readability and processing speed.

RULE: Dim and fill variables for items pulled from the Request(“”) object rather than calling the Request(“”) object continuously.

RATIONAL: Using variables filled from the Request(“”) Object allows for easier readability of the code, as the coder can document what the data being pulled from the object is. Continued use of variables is also faster to process than Request(“”) calls and less confusing.

Database Calls and Structure

RULE: Use all CAPITAL LETTERS for Common SQL commands. Ex: “SELECT Member_ID FROM Members WHERE…”

RATIONAL: Allows for increased SQL statement readability

RULE: Avoid “SELECT *” statements. Use “SELECT field1, field2, field3…”

RATIONAL: Allows for increased SQL statement readability and cuts down on transfer of unneeded data

RULE: Normalize tables where possible

RATIONAL: Increases the speed of data processing

RULE: Index columns that will be updated regularly and have a variety of options. Ex: Index a Rank Column, but not a Gender Column.

RATIONAL: Increases the speed of data processing and readability of table data

RULE: Minimize the use of not equal operations, <> or !=. SQL Server has to scan a table or index to find all values to see if they are not equal to the value given in the expression. Try rephrasing the expression using ranges: WHERE KeyColumn < 'TestValue' AND KeyColumn > 'TestValue'

RATIONAL: Increases the speed of data processing

Common Names and Customs

Use a variable named “Abort” to dictate whether or not the script should abort from errors in the form data or script.
Use a hidden field called “hdnSubmitted” that is set to true to dictate to the script that a form has been submitted
Use a variable named “strErrorMsg” to hold error messages from the page

Peer Review

Prior to launch of the script, another members of the SCL staff (hopefully your superior) should review your code

Development Site and Testing

All members of the SCL staff and coding team should use the development site for all edits to DB pages and scripts.
Pages should be thoroughly tested on the Development site using the development database and dossiers.
After pages are tested and reviewed, they may be copied to the live server.

Code Layout – Tabs and White Space

Indents Indentations should be a standard width of four spaces. Please note that this does not actually mean you hit space four times; rather, your editor should be set up so that a tab size is four spaces wide. This is normally the default setting. Indentations should be made under any overarching or containing tag. This means that a non-font tag that contains a block of code should have the code it contains indented. The closing tag should match the original indentation of the opening tag.