Application Development Coding Standards

1Introduction

This document provides guidelines and recommendations for standardizing thecoding practices within the ITS Department. Although it is hoped that much of this document will be adhered to, most of the items are merely recommendations. The goal of providing these recommendations is to improve consistency and readability, making the job of maintaining code easier for all developers.

2General Coding Standards

2.1Security

Parameter validation should be performed by checking for type, size and range.
Do not rely exclusively on client side validation. Client side validation is performed as a convenience for the user, but all validation should be performed on the server.
Do not store userID, security credentials or permissions, or other critical information on the client where it could be manipulated to compromise security or processing
Provide a logout mechanism
Security credentials required in code should be stored in a single encrypted configuration/settings file and referenced by all other code.
Call-outs to external programs should use secure protocols (https, sFTP (secure FTP))

2.2Exception Handling

Exception handling should be used either by an overarching environment (e.g. Nautical), or directly in the code (try/catch). The purpose of exception handling is twofold, to provide a good user experience preventing applications from crashing ingloriously leaving the user hanging and to prevent system error messages from displaying system information that might be useful to hackers.

2.3Naming

2.3.1General Naming Recommendations

All entities should be named for readability, using readable English words or phrases and should use CamelCase capitalization where the words are joined without spaces and are capitalized within the compound as depicted in the examples that follow. The primary function or purpose of any entity should be obvious from its name. In general, "verb-noun" and "adjective-noun" phrases are the most natural choice. Singular nouns are preferred.

courseList.cfm

EmployeeClassification.cfc

formValidation.js

contactUs.html

username

firstName

2.3.2Abbreviations

Abbreviations and acronyms should be used sparingly. Widely understood acronyms or abbreviations may be used, such as UWF, ID, CGI and URL. Such abbreviations and acronyms will be uppercase, unless they are part of a filename that forms part of a URL, in which case they will be lowercase.

userID

UWFStudent

2.3.3File Naming

URL-accessible filenames may contain upper and lowercase characters, but should never begin with uppercase. Exceptions to this recommendation are components and classes. Filenames should never contain spaces.

2.3.4Components/Classes

Component names should contain mixed case words, beginning with an uppercase character. Method names, property names, and instance names should be mixed case beginning with a lowercase character.

2.3.5Attributes, Fields, Functions, Methods, Parameters, Properties & Variables

All of these will be mixed case beginning with a lowercase character. Boolean attributes should generally begin with “is” or “has.” Function and method names should be a verb or verbNoun.

isDone

has Access

read()

getStatus()

2.4Comments

Change history comments are required at the top of each file and function.

Comments should be made to prevent them from being viewable by end users whenever possible so that processing logic is not revealed.

Comments should be provided at the top of files and before each function, describing the purpose of the file or function. Avoid excessive characters within a comment block, for the purpose of providing visual bars or divisions. These characters can provide erroneous results when using tools to search the code.

Comments should be included any place where additional information will be of value to aid in future maintenance. Keep in mind that the original developer may not perform all maintenance.

2.5Layout

Indentation should be based on 4-space tabs. Actual TAB characters are preferable to multiple SPACE characters to reduce file size and make editing easier.

Components should include an init function which is to be called when an instance of the object is created.

Functions which contain DB2 queries should include an argument for the datasource. This will allow the appropriate datasource to be used for DB2 cost analysis.

2.6Modularity

Modularity breaks up application processing into logic chunks making it easier to understand and isolating one chunk of processing from another. Ideally, the main page of an application would only have control of flow logic providing a single place where a programmer can look and understand the flow of an application and that page would use includes, components and functions to break up the processing.

Appendix A – ColdFusion

Queries

Query names should begin with a “q” or “qry” to easily identify query data. References to query fieldnames should always be scoped to include the query name for readability and to prevent name collisions.

<cfset variables.fullName = qName.firstName“ “qName.lastName

Within components, queries should also be initialized and scoped prior to use to prevent name collisions.

cfquery name=”qName” datasource=”#request.ds#”

SELECT

TO.COLUMN_ONE,

TT.COLUMN_TWO

FROM

TABLE_ONE TO,

TABLE_TWO TT

WHERE

TO.TABLE_ONE_ID = TT.TABLE_TWO_ID

AND

TT.TABLE_TWO_ID = 10

ORDER BY

TO.TABLE_ONE_ORDER_KEY

</cfquery>

Use of the <cfqueryparam> tag to pass dynamic data to queries is required. Proper usage always requires specifying the data type (cfsqltype) and where appropriate the length (maxlength).

Comments

At the beginning of each template or component, the following comment block should be added. This comment block will also be used to track revisions made to the file.

<!---

Location: /utility/test/myTemplate.cfm

Date: 1/1/2008

Author: Joe Programmer

Purpose: Serves as an example for developer

Notes:

changeHistory

HISTORY ------

Date:

Author:

Purpose:

</changeHistory

--->

Scope

Within a ColdFusion component, there are three scopes that are of particular importance. The variables scope refers to non-public variables. These variables are accessible within the component, but not external to the component. The var scope makes a variable local to the function in which it was declared. Variables in the var scope must be declared at the beginning of a function. The third scope is this scope, which refers to a public instance of the data. Public data is accessible outside the component where it is declared.

var – local to function
variables – local to component
this – public data

cfcomponent

</cffunction

</cffunction

</cfcomponent

Attribute Values

Attribute values to all tags (except cfset, cfif and cfreturn)should be quoted, usually with double quotes ("). Single quotes (') may be used if the attribute value already contains a double quote.

In cfset, the attribute name is always a variable name (possibly evaluated, e.g., arr[i]) and the apparent attribute value is really an expression. In cfif and cfreturn, the 'attribute' is really an expression. String values in expressions will be quoted (with " or ' as appropriate). Numeric values in expressions will not be quoted. Variable names in expressions will not be quoted, so that pound signs (#) are not needed, i.e.variableName instead of "#variableName#". The attribute name in cfset - the variable name - will not be quoted.

Do not use evaluated variable names like "caller.#resultVariable#" or "varname_#index#" - use caller[resultVariable] or variables["varname_" & index] instead.

Forboolean attribute values, use true and false rather than numeric values. The value may be quoted or unquoted. In cfset the value should be unquoted.

Other

The cfinclude tag and functions are more efficient from a processing perspective and generally should be favored over components and custom tags.

A-1

Appendix B – ActionScript

Scope

ActionScript 3.0 provides four special attributes that control access to properties defined inside a class:public,private,protected, andinternal.

Thepublicattribute makes a property visible anywhere in your script. For example, to make a method available to code outside its package, you must declare the method with thepublicattribute. This is true for any property, whether it is declared using thevar,const, orfunctionkeywords.

Theprivateattribute makes a property visible only to callers within the property's defining class. This behavior differs from that of theprivateattribute in ActionScript 2.0, which allowed a subclass to access a private property in a superclass. Another significant change in behavior has to do with run-time access. In ActionScript 2.0, theprivatekeyword prohibited access only at compile time and was easily circumvented at run time. In ActionScript 3.0, this is no longer true. Properties that are marked asprivateare unavailable at both compile time and run time.

Theprotectedattribute, which is new for ActionScript 3.0, makes a property visible to callers within its own class or in a subclass. In other words, a protected property is available within its own class or to classes that lie anywhere below it in the inheritance hierarchy. This is true whether the subclass is in the same package or in a different package.

The ActionScript 3.0protectedattribute is also similar to theprotectedattribute in Java, but differs in that the Java version also permits access to callers within the same package. Theprotectedattribute is useful when you have a variable or method that your subclasses need but that you want to hide from code that is outside the inheritance chain.

Theinternalattribute, which is new for ActionScript 3.0, makes a property visible to callers within its own package. This is the default attribute for code inside a package, and it applies to any property that does not have any of the following attributes:

public

private

protected

a user-defined namespace

Theinternalattribute is similar to the default access control in Java, although in Java there is no explicit name for this level of access, and it can be achieved only through the omission of any other access modifier. Theinternalattribute is available in ActionScript 3.0 to give you the option of explicitly signifying your intent to make a property visible only to callers within its own package.

Comments

ActionScript variables and methods need to be commented using the ASDocs format to allow for standardized documentation. Information about writing ASDocs can be found here.

B-1

Appendix C – .NET

C-1